Py-FSRS is a python package that allows developers to easily create their own spaced repetition system using the Free Spaced Repetition Scheduler algorithm.

Installation

You can install the fsrs python package from PyPI using pip:

pip install fsrs

Quickstart

Import and initialize the FSRS scheduler

from fsrs import FSRS, Card, Rating

f = FSRS()

Create a new Card object

# all new cards are 'due' immediately upon creation
card = Card()

Choose a rating and review the card

# you can choose one of the four possible ratings
"""
Rating.Again # forget; incorrect response
Rating.Hard # recall; correct response recalled with serious difficulty
Rating.Good # recall; correct response after a hesitation
Rating.Easy # recall; perfect response
"""

rating = Rating.Good

card, review_log = f.review_card(card, rating)

See when the card is due next

from datetime import datetime, timezone

due = card.due

# how much time between when the card is due and now
time_delta = due - datetime.now(timezone.utc)

print(f"Card due: at {repr(due)}")
print(f"Card due in {time_delta.seconds} seconds")

"""
> Card due: at datetime.datetime(2024, 7, 12, 18, 16, 4, 429428, tzinfo=datetime.timezone.utc)
> Card due in: 599 seconds
"""

Usage

Custom scheduler

You can initialize the FSRS scheduler with your own custom weights as well as desired retention rate and maximum interval.

f = FSRS(
    w=(
        0.4197,
        1.1869,
        3.0412,
        15.2441,
        7.1434,
        0.6477,
        1.0007,
        0.0674,
        1.6597,
        0.1712,
        1.1178,
        2.0225,
        0.0904,
        0.3025,
        2.1214,
        0.2498,
        2.9466,
        0.4891,
        0.6468,
    ),
    request_retention=0.85,
    maximum_interval=3650,
)

Advanced reviewing of cards

Aside from using the convenience method review_card, there is also the repeat method:

from datetime import datetime, timezone

# custom review time (must be UTC)
review_time = datetime(2024, 7, 13, 20, 7, 56, 150101, tzinfo=timezone.utc)

scheduling_cards = f.repeat(card, review_time)

# can get updated cards for each possible rating
card_Again = scheduling_cards[Rating.Again].card
card_Hard = scheduling_cards[Rating.Hard].card
card_Good = scheduling_cards[Rating.Good].card
card_Easy = scheduling_cards[Rating.Easy].card

# get next review interval for each rating
scheduled_days_Again = card_Again.scheduled_days
scheduled_days_Hard = card_Hard.scheduled_days
scheduled_days_Good = card_Good.scheduled_days
scheduled_days_Easy = card_Easy.scheduled_days

# choose a rating and update the card
rating = Rating.Good
card = scheduling_cards[rating].card

# get the corresponding review log for the review
review_log = scheduling_cards[rating].review_log

Serialization

Card and ReviewLog objects are JSON-serializable via their to_dict and from_dict methods for easy database storage:

# serialize before storage
card_dict = card.to_dict()
review_log_dict = review_log.to_dict()

# deserialize from dict
new_card = Card.from_dict(card_dict)
new_review_log = ReviewLog.from_dict(review_log_dict)

Reference

Card objects have one of four possible states

State.New # Never been studied
State.Learning # Been studied for the first time recently
State.Review # Graduate from learning state
State.Relearning # Forgotten in review state

There are four possible ratings when reviewing a card object:

Rating.Again # forget; incorrect response
Rating.Hard # recall; correct response recalled with serious difficulty
Rating.Good # recall; correct response after a hesitation
Rating.Easy # recall; perfect response

Algorithm

For a brief overview of the FSRS algorithm, please see ALGORITHM.md.

Contribute

Checkout CONTRIBUTING to help improve Py-FSRS!