├── public
    └── .gitkeep
├── .gitignore
├── db
    ├── reload-functions.sh
    ├── tables.sql
    ├── api.sql
    └── functions.sql
├── views
    ├── home.erb
    ├── layout.erb
    └── card.erb
├── web.rb
├── LICENSE
└── README.md


/public/.gitkeep:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | public/*
2 | !public/.gitkeep
3 | 


--------------------------------------------------------------------------------
/db/reload-functions.sh:
--------------------------------------------------------------------------------
 1 | #!/bin/sh
 2 | # RELOAD SQL FUNCTIONS WITHOUT LOSING DATA
 3 | 
 4 | # Assumes you have already created database & tables:
 5 | # createuser srs
 6 | # createdb -O srs srs
 7 | # psql -U srs -d srs -f tables.sql
 8 | 
 9 | psql -U srs -d srs -c "drop schema srs cascade"
10 | psql -U srs -d srs -c "create schema srs"
11 | psql -U srs -d srs -c "set search_path = srs,public"
12 | psql -U srs -d srs -f functions.sql
13 | psql -U srs -d srs -f api.sql
14 | 
15 | psql -U srs -d srs
16 | 


--------------------------------------------------------------------------------
/views/home.erb:
--------------------------------------------------------------------------------
 1 | <section id="decks">
 2 | <% if @decks.size == 0 %>
 3 |   <p>All done.</p>
 4 | <% else %>
 5 |   <ul>
 6 |   <% @decks.each do |x| %>
 7 |     <li>
 8 |       <a href="/next?deck=<%= x[:deck] %>"><%= x[:deck] %></a>
 9 |       (<%= x[:count] %>)
10 |     </li>
11 |   <% end %>
12 |   </ul>
13 | <% end %>
14 | </section>
15 | 
16 | <section id="add">
17 | <h1>add</h1>
18 | <form action="/" method="post">
19 |   <label>deck:
20 |     <input type="text" name="deck" value="learn">
21 |   </label>
22 |   <label>front:
23 |     <textarea id="front" name="front"></textarea>
24 |   </label>
25 |   <label>back:
26 |     <textarea name="back"></textarea>
27 |   </label>
28 |   <input type="submit" value="add">
29 | </form>
30 | </section>
31 | <script>
32 | window.onload = function() {
33 |   document.getElementById('front').focus();
34 | };
35 | </script>
36 | 


--------------------------------------------------------------------------------
/web.rb:
--------------------------------------------------------------------------------
 1 | require 'sinatra'
 2 | require 'pg'
 3 | require 'json'
 4 | 
 5 | # SQL query-builder:
 6 | # a('decks') = "select ok, js from srs.decks()"
 7 | # a('review', 9, 'good') = "select ok, js from srs.review($1,$2)", [9, 'good']
 8 | # returns boolean ok, and parsed JSON
 9 | class DBAPI
10 |   def initialize
11 |     @db = PG::Connection.new(dbname: 'srs', user: 'srs')
12 |   end
13 |   def a(func, *params)
14 |     qs = '(%s)' % (1..params.size).map {|i| "$#{i}"}.join(',')
15 |     sql = "select ok, js from srs.#{func}#{qs}"
16 |     r = @db.exec_params(sql, params)[0]
17 |     [
18 |       (r['ok'] == 't'),
19 |       JSON.parse(r['js'], symbolize_names: true)
20 |     ]
21 |   end
22 | end
23 | API = DBAPI.new
24 | 
25 | get '/' do
26 |   ok, @decks = API.a('decks')
27 |   erb :home
28 | end
29 | 
30 | post '/' do
31 |   API.a('add', params[:deck], params[:front], params[:back])
32 |   redirect to('/')
33 | end
34 | 
35 | get '/next' do
36 |   ok, @card = API.a('next', String(params[:deck]))
37 |   redirect to('/') unless ok
38 |   erb :card
39 | end
40 | 
41 | post '/card/:id/edit' do
42 |   API.a('edit', params[:id], params[:deck], params[:front], params[:back])
43 |   redirect to('/next?deck=%s' % params[:deck])
44 | end
45 | 
46 | post '/card/:id/review' do
47 |   ok, c = API.a('review', params[:id], params[:rating])
48 |   redirect to('/next?deck=%s' % c[:deck])
49 | end
50 | 
51 | 


--------------------------------------------------------------------------------
/db/tables.sql:
--------------------------------------------------------------------------------
 1 | create type public.state as enum ('new', 'learning', 'review', 'relearning');
 2 | create type public.rating as enum ('again', 'hard', 'good', 'easy');
 3 | 
 4 | create table public.cards (
 5 | 	id integer primary key generated by default as identity,
 6 | 	deck varchar(10) not null default 'in',
 7 | 	front text not null unique,         -- content (question)
 8 | 	back text not null,                 -- content (answer)
 9 | 	state state not null default 'new', -- state of the card (new, learning, review, relearning)
10 | 	due timestamptz(0) not null default now() - interval '1 minute', -- when card next due for review
11 | 	scheduled_days integer not null default 0, -- days until card is due (interval until next scheduled)
12 | 	elapsed_days integer not null default 0, -- days since card was last reviewed
13 | 	last_review timestamptz(0),         -- most recent review date/time
14 | 	reps integer not null default 0,    -- times the card has been reviewed
15 | 	lapses integer not null default 0,  -- times the card was forgotten or remembered incorrectly
16 | 	stability numeric not null default 0,  -- how well the information is retained
17 | 	difficulty numeric not null default 0  -- inherent difficulty of the card content
18 | );
19 | create index cardeck on cards(deck);
20 | create index cardue on cards(due);
21 | 
22 | -- all functions in schema srs, so that you can ...
23 | -- drop schema srs cascade; create schema srs;
24 | -- ... to replace all functions, but not lose table data.
25 | create schema srs;
26 | set search_path = srs, public;
27 | 
28 | 


--------------------------------------------------------------------------------
/views/layout.erb:
--------------------------------------------------------------------------------
 1 | <!doctype html>
 2 | <html>
 3 | <head>
 4 | <meta charset="utf-8">
 5 | <meta name="viewport" content="width=device-width, initial-scale=1">
 6 | <title>SRS</title>
 7 | <style>
 8 | header { font-size: 0.8em; font-family: sans-serif; margin-bottom: 2em }
 9 | main { font-family: Georgia; font-size: 20px; margin: 1em }
10 | section { margin-bottom: 4em }
11 | h1 { font-family: sans-serif; font-size: 1.3em; font-weight: normal }
12 | input, textarea { font-family: inherit }
13 | input[type=text] { width: 6em }
14 | textarea { width: 30em; height: 5em }
15 | audio, video { display: block }
16 | section#front, section#back { font-size: 1.8em }
17 | section#add input, section#edit input, textarea { display: block; margin-bottom: 1em }
18 | section#add input[type=submit] { background-color: #0c0; color: #000 }
19 | section#review input[type=submit] { display: inline; margin-right: 2em }
20 | button#play { background-color: #509; color: #fff }
21 | section#reveal button#flip { background-color: #000; color: #fff }
22 | section#review input#again { background-color: #900; color: #fff }
23 | section#review input#hard { background-color: #ff0; color: #000 }
24 | section#review input#good { background-color: #0f0; color: #000 }
25 | section#review input#easy { background-color: #00f; color: #fff }
26 | section#review button#showedit { float: right }
27 | </style>
28 | <!-- minimal favicon so browser doesn't keep looking for one -->
29 | <link rel="icon" href="data:image/x-icon;base64,AAABAAEAEBACAAEAAQCwAAAAFgAAACgAAAAQAAAAIAAAAAEAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA">
30 | </head>
31 | <body>
32 | <header><a href="/">SRS</a></header>
33 | <main id="main">
34 | 
35 | <%= yield %>
36 | 
37 | </main>
38 | </body>
39 | </html>
40 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | License for Free Spaced Repetition Scheduler (FSRS) algorithm:
 2 | 
 3 | MIT License
 4 | 
 5 | Copyright (c) 2024 Open Spaced Repetition
 6 | 
 7 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 8 | 
 9 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
10 | 
11 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
12 | 
13 | ----------
14 | 
15 | "UNLICENSE" LICENSE FOR THE REST:
16 | 
17 | This is free and unencumbered software released into the public domain.
18 | 
19 | Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
20 | 
21 | In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
22 | 
23 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 | 
25 | For more information, please refer to <https://unlicense.org>
26 | 
27 | 


--------------------------------------------------------------------------------
/db/api.sql:
--------------------------------------------------------------------------------
  1 | -- API FUNCTIONS: USE JUST THESE
  2 | 
  3 | 
  4 | 
  5 | -- list decks with count of cards due
  6 | -- use this to call next(deck)
  7 | --| [{deck, count int}]
  8 | create function srs.decks(
  9 | 	out ok boolean, out js json) as $$
 10 | begin
 11 | 	ok = true;
 12 | 	js = coalesce((select json_agg(r) from (
 13 | 		select deck, count(id)
 14 | 		from cards
 15 | 		where due < now()
 16 | 		or due is null
 17 | 		group by deck
 18 | 		order by deck
 19 | 	) r), '[]');
 20 | end;
 21 | $$ language plpgsql;
 22 | 
 23 | 
 24 | 
 25 | -- add a new card. deck name is whatever you want, new or existing
 26 | -- front and back are HTML, so if if you need < & >, escape it yourself
 27 | --| {id int} || {error}
 28 | create function srs.add(_deck text, _front text, _back text,
 29 | 	out ok boolean, out js json) as $$
 30 | declare
 31 | 	err text;
 32 | begin
 33 | 	ok = true;
 34 | 	with nu as (
 35 | 		insert into cards (deck, front, back)
 36 | 		values ($1, $2, $3)
 37 | 		returning id
 38 | 	) select row_to_json(nu.*) into js from nu;
 39 | exception
 40 | 	when others then get stacked diagnostics err = message_text;
 41 | 	js = json_build_object('error', err);
 42 | 	ok = false;
 43 | end;
 44 | $$ language plpgsql;
 45 | 
 46 | 
 47 | 
 48 | -- get next card due in this deck, or ok=false if none due
 49 | --| {id int, deck, front, back} || {error}
 50 | create function srs.next(_deck text,
 51 | 	out ok boolean, out js json) as $$
 52 | begin
 53 | 	ok = true;
 54 | 	js = row_to_json(r) from (
 55 | 		select id, deck, front, back
 56 | 		from cards
 57 | 		where deck = $1
 58 | 		and due < now()
 59 | 		or due is null
 60 | 		order by due nulls first limit 1
 61 | 	) r;
 62 | 	if js is null then
 63 | 		ok = false;
 64 | 		js = json_build_object('error', 'not found');
 65 | 	end if;
 66 | end;
 67 | $$ language plpgsql;
 68 | 
 69 | 
 70 | 
 71 | -- edit a card's deck, front, or back content
 72 | --| {} || {error}
 73 | create function srs.edit(_id integer, _deck text, _front text, _back text,
 74 | 	out ok boolean, out js json) as $$
 75 | declare
 76 | 	err text;
 77 | begin
 78 | 	update cards
 79 | 	set deck = $2, front = $3, back = $4
 80 | 	where id = $1;
 81 | 	ok = true;
 82 | 	js = '{}';
 83 | exception
 84 | 	when others then get stacked diagnostics err = message_text;
 85 | 	js = json_build_object('error', err);
 86 | 	ok = false;
 87 | end;
 88 | $$ language plpgsql;
 89 | 
 90 | 
 91 | 
 92 | -- rate card as 'again', 'hard', 'good', or 'easy'
 93 | -- returns deck of this card to be used in next(deck)
 94 | --| {deck} || {error}
 95 | create function srs.review(_cardid integer, rating,
 96 | 	out ok boolean, out js json) as $$
 97 | declare
 98 | 	err text;
 99 | begin
100 | 	perform card_review($1, $2);
101 | 	ok = true;
102 | 	js = row_to_json(r) from (
103 | 		select deck from cards where id = $1
104 | 	) r;
105 | exception
106 | 	when others then get stacked diagnostics err = message_text;
107 | 	js = json_build_object('error', err);
108 | 	ok = false;
109 | end;
110 | $$ language plpgsql;
111 | 
112 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Spaced Repetition in PostgreSQL functions
  2 | 
  3 | 
  4 | ## origin
  5 | 
  6 | [Free Spaced Repetition Scheduler (v5)](https://github.com/open-spaced-repetition)
  7 | 
  8 | 
  9 | 
 10 | ## this PostgreSQL version
 11 | 
 12 | Written by [Derek Sivers](https://sive.rs/) in September 2024.
 13 | I'm happy to discuss it, so [email me](https://sive.rs/contact) if you want, especially if you find errors.
 14 | Take it and adapt it for you or others to use, since this implementation is meant for my own personal use, suited for just me.
 15 | I gave my parts the "unlicense" so you don't need to credit me.
 16 | 
 17 | 
 18 | 
 19 | ## install
 20 | 
 21 | ```
 22 | cd db/
 23 | createuser srs
 24 | createdb -O srs srs
 25 | psql -U srs -d srs -f tables.sql
 26 | sh reload-functions.sh
 27 | ```
 28 | 
 29 | 
 30 | 
 31 | ## API (use only this)
 32 | 
 33 | | API function | parameters | purpose |
 34 | |--------------|-------|---------|
 35 | | **add** | deck, front, back | create a new card with this content |
 36 | | **edit** | cards.id, deck, front, back | update this card's content |
 37 | | **decks** |  | list how many cards due in each deck |
 38 | | **next** | deck | get next due card from this deck |
 39 | | **review** | cards.id, rating | after quizzing, rate card as again, hard, good, or easy |
 40 | 
 41 | Every API function returns "ok" boolean and "js" JSON.
 42 | If "ok" is false, "js" will be {"error": "explanation"}
 43 | 
 44 | 
 45 | 
 46 | ## usage
 47 | 
 48 | ```sql
 49 | select add('pets', 'My first dog?', 'Charlie');
 50 | select add('pets', 'My last dog?', 'Snoopy');
 51 | select add('places', 'Capital of Azerbaijan?', 'Bakoo');
 52 | 
 53 | select edit(3, 'places', 'Capital of Azerbaijan?', 'Baku');
 54 | 
 55 | select decks();
 56 | 
 57 | select next('pets');
 58 | select review(1, 'hard');
 59 | 
 60 | select next('pets');
 61 | select review(2, 'easy');
 62 | ```
 63 | 
 64 | Front and Back content is interpreted as HTML, so put media files into public/ directory then use HTML to present them:
 65 | 
 66 | ```sql
 67 | select add('places',
 68 |   'How to say this place? <img src="paris.jpg">',
 69 |   'Paris <audio src="paris.mp3"></audio>');
 70 | ```
 71 | 
 72 | 
 73 | 
 74 | ## functions.sql (behind the scenes)
 75 | 
 76 | The Free Spaced Repetition Scheduler is in functions.sql,
 77 | copied from [algorithm.ts](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/algorithm.ts)
 78 | and [basic\_scheduler.ts](https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/impl/basic_scheduler.ts)
 79 | 
 80 | Thank you to [the wonderful people](https://github.com/orgs/open-spaced-repetition/people) who work so hard on this.
 81 | 
 82 | 
 83 | 
 84 | ## omitted
 85 | 
 86 | I don't need fuzzing, undo/rollback, log analysis optimization, or differentiation between basic versus long term scheduling, so I didn't add those.
 87 | I've used Anki every day for 15+ years, so I know what I do and don't need.
 88 | Simplification was my mission.
 89 | 
 90 | 
 91 | 
 92 | ## web, using Ruby
 93 | 
 94 | ```
 95 | gem install pg
 96 | gem install sinatra
 97 | ruby web.rb
 98 | ```
 99 | 
100 | HTML in the views/ directory.
101 | 
102 | / webroot in public/ is for cards' media files.
103 | 
104 | 
105 | 
106 | ## TODO
107 | 
108 | 1. media play button smarter
109 | 2. test against FSRS to make sure I got scheduler right
110 | 
111 | 


--------------------------------------------------------------------------------
/views/card.erb:
--------------------------------------------------------------------------------
  1 | <style>
  2 | section#back, section#review, section#edit, button#play { display: none }
  3 | </style>
  4 | 
  5 | <!-- because browsers won't auto-play audio/video without interaction first -->
  6 | <button id="play">play</button>
  7 | 
  8 | <section id="front">
  9 | <%= @card[:front] %>
 10 | </section>
 11 | 
 12 | <section id="reveal">
 13 |   <button id="flip">show</button>
 14 | </section>
 15 | 
 16 | <section id="back">
 17 | <%= @card[:back] %>
 18 | </section>
 19 | 
 20 | <section id="review">
 21 | <form action="/card/<%= @card[:id] %>/review" method="post">
 22 |   <label>1 <input id="again" type="submit" name="rating" value="again"></label>
 23 |   <label>2 <input id="hard"  type="submit" name="rating" value="hard"></label>
 24 |   <label>3 <input id="good"  type="submit" name="rating" value="good"></label>
 25 |   <label>4 <input id="easy"  type="submit" name="rating" value="easy"></label>
 26 | </form>
 27 | <button id="showedit">edit</button>
 28 | </section>
 29 | 
 30 | <section id="edit">
 31 | <form action="/card/<%= @card[:id] %>/edit" method="post">
 32 |   <label>deck:
 33 |     <input type="text" name="deck" value="<%= @card[:deck] %>">
 34 |   </label>
 35 |   <label>front:
 36 |     <textarea name="front"><%= Rack::Utils.escape_html(@card[:front]) %></textarea>
 37 |   </label>
 38 |   <label>back:
 39 |     <textarea name="back"><%= Rack::Utils.escape_html(@card[:back]) %></textarea>
 40 |   </label>
 41 |   <input type="submit" value="update">
 42 | </form>
 43 | </section>
 44 | 
 45 | <script>
 46 | // global array of audio/video elements & index
 47 | let media = [];
 48 | let i = 0;
 49 | 
 50 | /* load global media[] array with <audio>/<video> in this <section id="id"> */
 51 | function loadmedia(id) {
 52 |   media = Array.from(document.querySelector(`#${id}`).querySelectorAll('audio, video'));
 53 |   i = 0;
 54 | }
 55 | 
 56 | /* play <audio>/<video> in global media[] array */
 57 | function playmedia() {
 58 |   if (i < media.length) {
 59 |     let av = media[i];
 60 |     av.play();
 61 |     av.addEventListener('ended', function onEnd() {
 62 |       av.removeEventListener('ended', onEnd);
 63 |       i++;
 64 |       playmedia();
 65 |     });
 66 |   }
 67 | }
 68 | 
 69 | /* stop each <audio>/<video> element in global media[] array */
 70 | function stopAll() {
 71 |   media.forEach(av => {
 72 |     av.pause();
 73 |     av.currentTime = 0;
 74 |   });
 75 | }
 76 | 
 77 | function focusflip () {
 78 |   document.getElementById('flip').focus();
 79 | }
 80 | 
 81 | function playallmedia() {
 82 |   i = 0;
 83 |   playmedia();
 84 | }
 85 | 
 86 | /* when front of card shows... */
 87 | window.onload = function() {
 88 |   /* load section#front media */
 89 |   loadmedia('front');
 90 |   if (media.length == 0) {
 91 |     /* flip button focused so you can just press [space] to show back */
 92 |     document.getElementById('flip').focus();
 93 |   } else {
 94 |     /* if there's <audio>/<video>, show, focus, enable [play] button */
 95 |     document.getElementById('play').style.display = 'block';
 96 |     document.getElementById('play').focus();
 97 |     document.getElementById('play').addEventListener('click', playallmedia);
 98 |     document.getElementById('play').addEventListener('click', focusflip);
 99 |   }
100 | };
101 | 
102 | /* [flip] button does a few things: */
103 | document.getElementById('flip').addEventListener('click', function() {
104 |   /* hide flip-button section, show answer and review buttons */
105 |   document.getElementById('play').removeEventListener('click', focusflip);
106 |   document.getElementById('reveal').style.display = 'none';
107 |   document.getElementById('back').style.display = 'block';
108 |   document.getElementById('review').style.display = 'block';
109 |   /* listen for 1 2 3 4 r to trigger buttons */
110 |   document.addEventListener('keydown', function(event) {
111 |     if (['1','2','3','4','r'].includes(event.key)) {
112 |       event.preventDefault();
113 |       document.getElementById({'1':'again','2':'hard','3':'good','4':'easy','r':'play'}[event.key]).click();
114 |     }
115 |   });
116 |   /* also edit button shows edit form (instead of review) */
117 |   document.getElementById('showedit').addEventListener('click', function() {
118 |     document.getElementById('review').style.display = 'none';
119 |     document.getElementById('edit').style.display = 'block';
120 |   });
121 |   /* stop playing front media, start playing back */
122 |   stopAll();
123 |   loadmedia('back');
124 |   playmedia();
125 |   /* redefine [play] button to load then play all media on page */
126 |   document.getElementById('play').innerHTML = 'replay';
127 |   document.getElementById('play').removeEventListener('click', playallmedia);
128 |   document.getElementById('play').addEventListener('click', loadmedia('main'));
129 |   document.getElementById('play').addEventListener('click', playallmedia);
130 | });
131 | 
132 | </script>
133 | 
134 | 


--------------------------------------------------------------------------------
/db/functions.sql:
--------------------------------------------------------------------------------
  1 | -- PRIVATE FUNCTIONS, all to serve the final one: card_review
  2 | -- Don't use these.  They use each other.  Instead, see api.sql
  3 | 
  4 | -- DECAY: CONSTANT: set to -0.5
  5 | create function decay() returns numeric as $$
  6 | 	select -0.5;
  7 | $$ language sql immutable;
  8 | 
  9 | -- FACTOR: CONSTANT: set to 19/81 (0.23456790123456790123)
 10 | create function factor() returns numeric as $$
 11 | 	select 19::numeric / 81;
 12 | $$ language sql immutable;
 13 | 
 14 | -- WEIGHTS: w(0) returns first, w(18) returns last
 15 | create function w(int) returns numeric as $$
 16 | 	select (array[0.4072, 1.1829, 3.1262, 15.4722, 7.2102, 0.5316,
 17 | 		1.0651, 0.0234, 1.616, 0.1544, 1.0824, 1.9813, 0.0953,
 18 | 		0.2975, 2.2042, 0.2407, 2.9466, 0.5034, 0.6567])[$1 + 1];
 19 | -- PostgreSQL array indices start at 1, so retrieve by adding 1 to param
 20 | $$ language sql immutable;
 21 | 
 22 | -- CONSTANT / default
 23 | create function request_retention() returns numeric as $$
 24 | 	select 0.9;
 25 | $$ language sql immutable;
 26 | 
 27 | -- CONSTANT / default
 28 | create function maximum_interval() returns integer as $$
 29 | 	select 36500;
 30 | $$ language sql immutable;
 31 | 
 32 | -- convert grade/rating ('again','hard','good','easy') into integer (1,2,3,4)
 33 | create function gradenum(g rating) returns integer as $$
 34 | 	select array_position(enum_range(null::rating), $1::rating);
 35 | $$ language sql immutable;
 36 | 
 37 | -- bind/"clamp" value $1 to be $2 minimum, $3 maximum, so $2 <= $1 <= $3
 38 | -- returns updated $1 within these limits
 39 | create function clamp(numeric, numeric, numeric) returns numeric as $$
 40 | 	select least(greatest($1, $2), $3);
 41 | $$ language sql immutable;
 42 | 
 43 | -- https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm
 44 | -- LaTeX formula:
 45 | -- I(r,s) = (r^{\frac{1}{DECAY}} - 1) / FACTOR \times s
 46 | -- not multiplied by s here, but that's done where it's called
 47 | -- param request_retention 0<request_retention<=1,Requested retention rate
 48 | create function calculate_interval_modifier(r numeric) returns numeric as $$
 49 | 	select (power(r, 1 / decay()) - 1) / factor();
 50 | $$ language sql immutable;
 51 | 
 52 | -- LaTeX formula:
 53 | -- S_0(G) = w_{G-1}
 54 | -- S_0 = \max \lbrace S_0,0.1\rbrace
 55 | -- param g Grade (rating) [1=again,2=hard,3=good,4=easy]
 56 | -- return Stability (interval when R=90%)
 57 | create function init_stability(g rating) returns numeric as $$
 58 | 	select greatest(w(gradenum(g) - 1), 0.1);
 59 | $$ language sql immutable;
 60 | 
 61 | -- original had 3 params, but 2nd and 3rd were only for fuzzing, I only need stability
 62 | -- param: s - Stability (interval when R=90%)
 63 | create function next_interval(s numeric) returns integer as $$
 64 | 	select least(greatest(1,
 65 | 		round(s * calculate_interval_modifier(request_retention()))
 66 | 	), maximum_interval());
 67 | $$ language sql immutable;
 68 | 
 69 | -- LaTeX formula:
 70 | -- w_7 \cdot \text{init} +(1 - w_7) \cdot \text{current}
 71 | -- param init $$w_2 : D_0(3) = w_2 + (R-2) \cdot w_3= w_2$$
 72 | -- param current $$D - w_6 \cdot (R - 2)$$
 73 | -- return difficulty
 74 | create function mean_reversion(init numeric, curr numeric) returns numeric as $$
 75 | 	select w(7) * init + (1 - w(7)) * curr;
 76 | $$ language sql immutable;
 77 | 
 78 | -- LaTeX formula:
 79 | -- \min \lbrace \max \lbrace D_0,1 \rbrace,10\rbrace
 80 | -- @param {number} difficulty $$D \in [1,10]$$
 81 | create function constrain_difficulty(d numeric) returns numeric as $$
 82 | 	select least(greatest(d, 1), 10);
 83 | $$ language sql immutable;
 84 | 
 85 | -- LaTeX formula:
 86 | -- D_0(G) = w_4 - e^{(G-1) \cdot w_5} + 1
 87 | -- D_0 = \min \lbrace \max \lbrace D_0(G),1 \rbrace,10 \rbrace
 88 | -- where the D_0(1)=w_4 when the first rating is good.
 89 | -- param g Grade (rating) [1=again,2=hard,3=good,4=easy]
 90 | -- return {number} Difficulty $$D \in [1,10]$$
 91 | create function init_difficulty(g rating) returns numeric as $$
 92 | 	select constrain_difficulty(w(4) - exp((gradenum(g) - 1) * w(5)) + 1);
 93 | $$ language sql immutable;
 94 | 
 95 | -- LaTeX formula:
 96 | -- \text{next}_d = D - w_6 \cdot (g - 3)
 97 | -- D^\prime(D,R) = w_7 \cdot D_0(4) +(1 - w_7) \cdot \text{next}_d
 98 | -- param d Difficulty $$D \in [1,10]$$
 99 | -- param g Grade (rating) [1=again,2=hard,3=good,4=easy]
100 | -- return {number} $$\text{next}_D$$
101 | create function next_difficulty(d numeric, g rating) returns numeric as $$
102 | 	select constrain_difficulty(
103 | 	  mean_reversion(init_difficulty('easy'), d - w(6) * (gradenum(g) - 3))
104 | 	);
105 | $$ language sql immutable;
106 | 
107 | -- LaTeX formula:
108 | -- S^\prime_r(D,S,R,G) = S\cdot(e^{w_8}\cdot (11-D)\cdot S^{-w_9}\cdot(e^{w_{10}\cdot(1-R)}-1)\cdot w_{15}(\text{if} G=2) \cdot w_{16}(\text{if} G=4)+1)
109 | -- param d Difficulty D \in [1,10]
110 | -- param s Stability (interval when R=90%)
111 | -- param r Retrievability (probability of recall)
112 | -- param g Grade (rating) [1=again,2=hard,3=good,4=easy]
113 | -- @return {number} S^\prime_r new stability after recall
114 | create function next_recall_stability(d numeric, s numeric, r numeric, g rating) returns numeric as $$
115 | 	with vars as (select
116 | 		case when 'hard' = g then w(15) else 1 end as hard_penalty,
117 | 		case when 'easy' = g then w(16) else 1 end as easy_bound
118 | 	)
119 | 	select clamp(
120 | 		s * (
121 | 			1 + exp(w(8)) * (11 - d) * power(s, -w(9)) *
122 | 			(exp((1 - r) * w(10)) - 1) *
123 | 			hard_penalty * easy_bound
124 | 		),
125 | 	0.01, maximum_interval()) from vars;
126 | $$ language sql immutable;
127 | 
128 | -- LaTeX formula:
129 | -- S^\prime_f(D,S,R) = w_{11}\cdot D^{-w_{12}}\cdot ((S+1)^{w_{13}}-1) \cdot e^{w_{14}\cdot(1-R)}
130 | -- param d Difficulty D \in [1,10]
131 | -- param s Stability (interval when R=90%)
132 | -- param r Retrievability (probability of recall)
133 | -- @return {number} S^\prime_f new stability after forgetting
134 | create function next_forget_stability(d numeric, s numeric, r numeric) returns numeric as $$
135 | 	select clamp(
136 | 		w(11) * power(d, -w(12)) *
137 | 		(power(s + 1, w(13)) - 1) *
138 | 		exp((1 - r) * w(14)),
139 | 	0.01, maximum_interval());
140 | $$ language sql immutable;
141 | 
142 | -- LaTeX formula:
143 | -- S^\prime_s(S,G) = S \cdot e^{w_{17} \cdot (G-3+w_{18})}
144 | -- param s Stability (interval when R=90%)
145 | -- param g Grade (rating) [1=again,2=hard,3=good,4=easy]
146 | -- @return {number} S^\prime_f new stability after forgetting
147 | create function next_short_term_stability(s numeric, g rating) returns numeric as $$
148 | 	select clamp(
149 | 		s * exp(w(17) * (gradenum(g) - 3 + w(18))),
150 | 	0.01, maximum_interval());
151 | $$ language sql immutable;
152 | 
153 | -- LaTeX formula:
154 | -- R(t,S) = (1 + \text{FACTOR} \times \frac{t}{9 \cdot S})^{\text{DECAY}}
155 | -- param elapsed_days since the last review
156 | -- param s Stability (interval when R=90%)
157 | -- @return {number} r Retrievability (probability of recall)
158 | create function forgetting_curve(days integer, s numeric) returns numeric as $$
159 | 	select power(1 + (factor() * days) / s, decay());
160 | $$ language sql immutable;
161 | 
162 | 
163 | -- This could be in API, but it relies so much on algorithm features, so putting it here.
164 | -- INPUT cards.id and rating ('again', 'hard', 'good', 'easy')
165 | -- update almost everything about it (except id/deck/front/back):
166 | -- update state, due, scheduled_days, stability, difficulty
167 | -- update reps, lapses, elapsed_days, last_review
168 | create function card_review(card_id int, grade rating, out nu cards) as $$
169 | declare
170 | 	previous cards; -- as it is now, before updating
171 | 	nu cards; -- as is will be when updated at function end
172 | begin
173 | 	select * into previous from cards where id = $1;
174 | 
175 | 	-- UPDATE: reps, lapses, last_review, elapsed_days
176 | 	-- (since these don't depend on previous.state)
177 | 	nu.reps = previous.reps + 1;
178 | 	if grade = 'again' then
179 | 		nu.lapses = previous.lapses + 1;
180 | 	else
181 | 		nu.lapses = previous.lapses;
182 | 	end if;
183 | 	if previous.last_review is null then
184 | 		nu.elapsed_days = 0;
185 | 	else
186 | 		nu.elapsed_days = extract(day from (now() - previous.last_review));
187 | 	end if;
188 | 	nu.last_review = now();
189 | 
190 | 	-- UPDATE: stability, difficulty, state, scheduled_days, due
191 | 	-- These depend on previous.state and grade/rating: case-within-case
192 | 	-- This approach has some duplication but much clarity
193 | 	case previous.state
194 | 	when 'new' then
195 | 		nu.difficulty = init_difficulty(grade);
196 | 		nu.stability = init_stability(grade);
197 | 		case grade
198 | 		when 'again' then
199 | 			nu.state = 'learning';
200 | 			nu.scheduled_days = 0;
201 | 			nu.due = now() + interval '1 minute';
202 | 		when 'hard' then
203 | 			nu.state = 'learning';
204 | 			nu.scheduled_days = 0;
205 | 			nu.due = now() + interval '5 minutes';
206 | 		when 'good' then
207 | 			nu.state = 'learning';
208 | 			nu.scheduled_days = 0;
209 | 			nu.due = now() + interval '10 minutes';
210 | 		when 'easy' then
211 | 			nu.state = 'review';
212 | 			nu.scheduled_days = next_interval(nu.stability);
213 | 			nu.due = now() + (nu.scheduled_days || ' days')::interval;
214 | 		end case;
215 | 	when 'learning', 'relearning' then
216 | 		nu.difficulty = next_difficulty(previous.difficulty, grade);
217 | 		nu.stability = next_short_term_stability(previous.stability, grade);
218 | 		case grade
219 | 		when 'again' then
220 | 			nu.state = previous.state;
221 | 			nu.scheduled_days = 0;
222 | 			nu.due = now() + interval '5 minutes';
223 | 		when 'hard' then
224 | 			nu.state = previous.state;
225 | 			nu.scheduled_days = 0;
226 | 			nu.due = now() + interval '10 minutes';
227 | 		when 'good' then
228 | 			nu.state = 'review';
229 | 			nu.scheduled_days = next_interval(nu.stability);
230 | 			nu.due = now() + (nu.scheduled_days || ' days')::interval;
231 | 		when 'easy' then
232 | 			nu.state = 'review';
233 | 			nu.scheduled_days = greatest(next_interval(nu.stability),
234 | 				1 + next_interval(next_short_term_stability(previous.stability, 'good'))
235 | 			);
236 | 			nu.due = now() + (nu.scheduled_days || ' days')::interval;
237 | 		end case;
238 | 	when 'review' then
239 | 		nu.difficulty = next_difficulty(previous.difficulty, grade);
240 | 		if grade = 'again' then
241 | 			nu.stability = next_forget_stability(
242 | 				previous.difficulty,
243 | 				previous.stability,
244 | 				forgetting_curve(previous.elapsed_days, previous.stability));
245 | 		else
246 | 			nu.stability = next_recall_stability(
247 | 				previous.difficulty,
248 | 				previous.stability,
249 | 				forgetting_curve(previous.elapsed_days, previous.stability),
250 | 				grade);
251 | 		end if;
252 | 		case grade
253 | 		when 'again' then
254 | 			nu.state = 'relearning';
255 | 			nu.scheduled_days = 0;
256 | 			nu.due = now() + interval '5 minutes';
257 | 		when 'hard' then
258 | 			nu.state = previous.state;
259 | 			nu.scheduled_days = next_interval(nu.stability);
260 | 			nu.due = now() + (nu.scheduled_days || ' days')::interval;
261 | 		when 'good' then
262 | 			nu.state = previous.state;
263 | 			nu.scheduled_days = greatest(
264 | 				next_interval(nu.stability),
265 | 				1 + next_recall_stability(
266 | 					previous.difficulty,
267 | 					previous.stability,
268 | 					forgetting_curve(previous.elapsed_days, previous.stability),
269 | 					'hard'
270 | 				)
271 | 			);
272 | 			nu.due = now() + (nu.scheduled_days || ' days')::interval;
273 | 		when 'easy' then
274 | 			nu.state = previous.state;
275 | 			nu.scheduled_days = greatest(
276 | 				next_interval(nu.stability),
277 | 				1 + next_recall_stability(
278 | 					previous.difficulty,
279 | 					previous.stability,
280 | 					forgetting_curve(previous.elapsed_days, previous.stability),
281 | 					'good'
282 | 				)
283 | 			);
284 | 			nu.due = now() + (nu.scheduled_days || ' days')::interval;
285 | 		end case; 
286 | 	end case;
287 | 
288 | 	-- UPDATE WITH NEW VALUES:
289 | 	update cards set
290 | 	reps = nu.reps,
291 | 	lapses = nu.lapses,
292 | 	last_review = nu.last_review,
293 | 	elapsed_days = nu.elapsed_days,
294 | 	stability = nu.stability,
295 | 	difficulty = nu.difficulty,
296 | 	state = nu.state,
297 | 	scheduled_days = nu.scheduled_days,
298 | 	due = nu.due
299 | 	where id = $1;
300 | end;
301 | $$ language plpgsql;
302 | 
303 | 


--------------------------------------------------------------------------------