v5.1.2

What's Changed

• Fix handling of multiple schedulers edge case by @joshdavham in #91

Full Changelog: v5.1.1...v5.1.2

v5.1.1

What's Changed

• Fix multiple schedulers edge case by @joshdavham in #90

Full Changelog: v5.1.0...v5.1.1

v5.1.0

What's Changed

• Optimizer is now compatible with python3.13 by @joshdavham in #86
• Compute optimal retention by @joshdavham in #87

Full Changelog: v5.0.1...v5.1.0

v5.0.1

What's Changed

• Add repr methods to Card, ReviewLog and Scheduler classes by @joshdavham in #83
• Only compute step loss on non-same-day reviews by @joshdavham in #84
• Prevent card id collisions by @joshdavham in #85

Full Changelog: v5.0.0...v5.0.1

v5.0.0

Py-FSRS v5.0.0

This release makes a major change to the ReviewLog class and additionally introduces the Optimizer class which can be optionally installed to compute an optimal set of Scheduler parameters based on previous ReviewLog objects.

Changes to ReviewLog

The ReviewLog class no longer stores the Card attribute and has been replaced with a simpler card_id attribute.

# Py-FSRS v4 (old)
class ReviewLog:

    card: Card
    rating: Rating
    review_datetime: datetime
    review_duration: int | None

# Py-FSRS v5 (new)
class ReviewLog:

    card_id: int
    rating: Rating
    review_datetime: datetime
    review_duration: int | None

If you've previously stored your ReviewLog objects as .json files, upgrading should be fairly simple

# Py-FSRS v4 (old)
{'card': {'card_id': 1737744147587,
  'state': 1,
  'step': 0,
  'stability': None,
  'difficulty': None,
  'due': '2025-01-24T18:42:27.587133+00:00',
  'last_review': None},
 'rating': 3,
 'review_datetime': '2025-01-24T18:42:27.587305+00:00',
 'review_duration': None}

# Py-FSRS v5 (new)
{'card_id': 1737744147587,
 'rating': 3,
 'review_datetime': '2025-01-24T18:42:27.587305+00:00',
 'review_duration': None}

Optional Optimizer

As mentioned above, a new optional Optimizer class has been added. Please see the updated README for more details.

What's Changed

• Add optional dev dependencies to pyproject.toml by @joshdavham in #76
• Stop using math.exp and math.pow by @joshdavham in #78
• Improve mypy gh action by @joshdavham in #79
• Test multiple versions of python in pytest gh action by @joshdavham in #80
• Remove mypy by @joshdavham in #81
• Add optional optimizer by @joshdavham in #82

Full Changelog: v4.1.2...v5.0.0

v5.0.0rc1

Pre-release

Full Changelog: v4.1.2...v5.0.0rc1

v4.1.2

What's Changed

• Fixes type bug where difficulty became an int if it exceeded the thresholds by @TWAnthony in #74

New Contributors

• @TWAnthony made their first contribution in #74

Full Changelog: v4.1.1...v4.1.2

v4.1.1

What's Changed

• Small upkeeping by @joshdavham in #69
• Clip post lapse stability by @joshdavham in #72

Full Changelog: v4.1.0...v4.1.1

v4.1.0

What's Changed

• Switch to official ruff gh action by @joshdavham in #66
• Add linear damping by @joshdavham in #67
• Fuzz more intervals by @joshdavham in #68

Full Changelog: v4.0.0...v4.1.0

v4.0.0

Py-FSRS v4.0.0

This release makes some major changes to the API, the required version of python and a couple of other changes.

At a high level:

• Py-FSRS now requires python 3.10+
• The scheduler can now randomly "fuzz" calculated review intervals
• The scheduler can now set explicit learning and relearning steps
• Card objects no longer have a New state (new cards now start off in the Learning state)
• Card objects now have different attributes
• The scheduler has been renamed from FSRS to Scheduler
• The repeat method has been replaced in favor of the review_card method

Upgrade from v3 -> v4

To upgrade, first make sure you're using python 3.10 or later.

Next, you'll want to review the updated README to get familiar with the new API, which should hopefully be mostly straightforward.

The tricky part will be in updating previous v3 cards to v4.

This was the old class schema for v3 Cards:

class Card:
    """
    Represents a flashcard in the FSRS system.

    Attributes:
        due (datetime): The date and time when the card is due next.
        stability (float): Core FSRS parameter used for scheduling.
        difficulty (float): Core FSRS parameter used for scheduling.
        elapsed_days (int): The number of days since the card was last reviewed.
        scheduled_days (int): The number of days until the card is due next.
        reps (int): The number of times the card has been reviewed in its history.
        lapses (int): The number of times the card has been lapsed in its history.
        state (State): The card's current learning state.
        last_review (datetime): The date and time of the card's last review.
    """

    due: datetime
    stability: float
    difficulty: float
    elapsed_days: int
    scheduled_days: int
    reps: int
    lapses: int
    state: State
    last_review: datetime

and here's the new class schema for v4 Cards:

class Card:
    """
    Represents a flashcard in the FSRS system.

    Attributes:
        card_id (int): The id of the card. Defaults to the epoch miliseconds of when the card was created.
        state (State): The card's current learning state.
        step (int | None): The card's current learning or relearning step or None if the card is in the Review state.
        stability (float | None): Core mathematical parameter used for future scheduling.
        difficulty (float | None): Core mathematical parameter used for future scheduling.
        due (datetime): The date and time when the card is due next.
        last_review (datetime | None): The date and time of the card's last review.
    """

    card_id: int
    state: State
    step: int | None
    stability: float | None
    difficulty: float | None
    due: datetime
    last_review: datetime | None

To upgrade your v3 cards to v4 cards, do the following:

• Set card_id to a unique integer value. Unless otherwise specified, new v4 cards will be set to the epoch miliseconds of when the card was created, but you are free to set it to anything else.
• If your card's state was set to New, convert it to Learning and set its stability and difficulty values to None
• If your card was in the New, Learning or Relearning state, set its step to 0, otherwise, if the v3 card was in the Review state, set its step to None
• Remove the following attributes from your v3 cards (these were removed since they don't affect scheduling)
  • elapsed_days
  • scheduled_days
  • reps
  • lapses
• If your v3 card previously didn't have a last_review attribute, create one and set it to None

Now as for upgrading your v3ReviewLog objects to v4 objects, this will likely require some custom migration on your part. Apologies for any inconvenience.

In either case, this was the old v3 ReviewLog class schema:

class ReviewLog:
    """
    Represents the log entry of Card that has been reviewed.
    Attributes:
        rating (Rating): The rating given to the card during the review.
        scheduled_days (int): The number of days until the card is due next.
        elapsed_days (int): The number of days since the card was last reviewed.
        review (datetime): The date and time of the review.
        state (State): The learning state of the card before the review.
    """

    rating: Rating
    scheduled_days: int
    elapsed_days: int
    review: datetime
    state: State

and here's the new v4 ReviewLog schema:

class ReviewLog:
    """
    Represents the log entry of a Card object that has been reviewed.

    Attributes:
        card (Card): Copy of the card object that was reviewed.
        rating (Rating): The rating given to the card during the review.
        review_datetime (datetime): The date and time of the review.
        review_duration (int | None): The number of miliseconds it took to review the card or None if unspecified.
    """

    card: Card
    rating: Rating
    review_datetime: datetime
    review_duration: int | None

Upgrading to the new scheduler should be simple enough, just review the new README and compare it to how you were previously using the scheduler.

What's Changed

• Major update and refactor by @joshdavham in #64

Full Changelog: v3.1.0...v4.0.0