spacedreppy 0.5.0

A spaced repetition Python library.

SpacedRepPy

A spaced repetition Python library implementing SM-2, Leitner, and FSRS-6 algorithms.

Installation

Use uv or pip to install spacedreppy.

uv add spacedreppy
# or
pip install spacedreppy

Usage

SM-2

from datetime import datetime, timezone
from spacedreppy import SM2Scheduler

scheduler = SM2Scheduler()

# Each call returns the next due timestamp and interval.
due_timestamp, interval = scheduler.compute_next_due_interval(
    attempted_at=datetime.now(timezone.utc), result=4
)

The result parameter is a quality score from the SM-2 algorithm:

Score	Meaning
0	Complete blackout — no recall at all
1	Incorrect response, but the correct answer seemed easy to recall once seen
2	Incorrect response, but the correct answer was remembered upon seeing it
3	Correct response with serious difficulty
4	Correct response after some hesitation
5	Perfect response with no hesitation

Scores of 3 or higher count as correct and advance the repetition schedule. Scores below 3 reset the interval.

Leitner System

from datetime import datetime, timezone
from spacedreppy import LeitnerScheduler

scheduler = LeitnerScheduler()

# result=1 for correct, result=0 for incorrect
due_timestamp, interval = scheduler.compute_next_due_interval(
    attempted_at=datetime.now(timezone.utc), result=1
)

The result parameter is a binary score:

Score	Meaning
0	Incorrect
1	Correct

Correct answers promote the card to the next box; incorrect answers send it back to the first box. The default box intervals (in days) are [1, 3, 7, 14, 30], but you can provide your own:

scheduler = LeitnerScheduler(intervals=[2, 5, 10])

FSRS-6

from datetime import datetime, timezone
from spacedreppy import FSRSScheduler

scheduler = FSRSScheduler()

# result: 1=Again, 2=Hard, 3=Good, 4=Easy
due_timestamp, interval = scheduler.compute_next_due_interval(
    attempted_at=datetime.now(timezone.utc), result=3
)

The result parameter is a rating from the FSRS algorithm:

Rating	Meaning
1 (Again)	Forgot the card
2 (Hard)	Remembered with serious difficulty
3 (Good)	Remembered after some hesitation
4 (Easy)	Remembered easily

FSRS-6 models memory with Stability (S) and Difficulty (D), using a power-law forgetting curve with 21 trainable parameters. You can customize the scheduler:

scheduler = FSRSScheduler(
    request_retention=0.85,   # target retention (default: 0.9)
    maximum_interval=365,     # max interval in days (default: 36500)
)

Custom model weights (e.g., from the FSRS optimizer) can also be provided:

scheduler = FSRSScheduler(weights=my_optimized_weights)

Development

This project uses uv for dependency management and just as a command runner.

# Install dependencies
just install

# Run tests
just test

# Run formatters
just codestyle

# Run all linting (tests + style + mypy + safety)
just lint

License

MIT