Multi-Language SRS

A Flutter package providing core logic for a multi-language spaced repetition system (SRS). This package implements the SM-2 algorithm for spaced repetition and provides data models and core functions for managing flashcards across multiple languages.

Features

• Spaced repetition algorithm based on SM-2 (used by Anki)
• Multi-language flashcard item model
• Core SRS functions for managing items and scheduling
• Backend-agnostic design (no persistence implementation)
• UI-less architecture (no Flutter widgets)

Installation

To use this package, add multi_language_srs as a dependency in your pubspec.yaml file:

dependencies:
  multi_language_srs: ^0.1.0

Then run:

flutter pub get

Usage

Basic Usage

import 'package:multi_language_srs/multi_language_srs.dart';

// Create a new SRS manager
final srsManager = SRSManager();

// Add a new flashcard item
final newItem = FlashcardItem(
  id: 'unique_id',
  languageId: 'es',
  question: '¿Cómo estás?',
  answer: 'How are you?',
);
srsManager.addItem(newItem);

// Record a review for an item
srsManager.recordReview('unique_id', ReviewOutcome.good);

// Get due items for today
final dueItems = srsManager.getDueItems(DateTime.now());

// Get due items for a specific language
final spanishDueItems = srsManager.getDueItems(DateTime.now(), languageId: 'es');

Creating Flashcard Items

// Create a basic flashcard with default SRS values
final basicCard = FlashcardItem(
  languageId: 'fr',
  question: 'Bonjour',
  answer: 'Hello',
);

// Create a flashcard with custom SRS values
final advancedCard = FlashcardItem(
  id: 'custom-id', // Optional: provide your own ID
  languageId: 'ja',
  question: 'こんにちは',
  answer: 'Hello',
  interval: 5, // Days until next review
  easeFactor: 2.1, // Difficulty factor
  reviews: 3, // Number of previous reviews
  nextReviewDate: DateTime(2025, 5, 1), // Custom next review date
);

Recording Reviews

// Record different review outcomes
srsManager.recordReview('card-id-1', ReviewOutcome.again); // Failed, reset interval
srsManager.recordReview('card-id-2', ReviewOutcome.hard);  // Difficult recall
srsManager.recordReview('card-id-3', ReviewOutcome.good);  // Successful recall
srsManager.recordReview('card-id-4', ReviewOutcome.easy);  // Very easy recall

Managing Items

// Update an existing item
final updatedItem = existingItem.copyWith(
  question: 'Updated question',
  answer: 'Updated answer',
);
srsManager.updateItem(updatedItem);

// Remove an item
srsManager.removeItem('card-id');

// Clear all items
srsManager.clear();

Persistence Integration

This package doesn't handle persistence directly. Here's an example of how to integrate with your own persistence solution:

// Load items from your storage
List<Map<String, dynamic>> loadedData = await yourStorageService.loadItems();
List<FlashcardItem> items = loadedData.map((json) => FlashcardItem.fromJson(json)).toList();

// Add items to the SRS manager
for (var item in items) {
  srsManager.addItem(item);
}

// When recording a review, save the updated item
final updatedItem = srsManager.recordReview('item-id', ReviewOutcome.good);
if (updatedItem != null) {
  await yourStorageService.saveItem(updatedItem.toJson());
}

Algorithm Details

This package implements the SM-2 algorithm with the following characteristics:

• Initial interval for a new card reviewed as "Good": 1 day
• Second review as "Good": 6 days
• Subsequent intervals: interval * easeFactor
• Initial ease factor: 2.5
• Ease factor adjustments:
  • Again: -0.20
  • Hard: -0.15
  • Good: +0.05
  • Easy: +0.15
• Minimum ease factor: 1.3

License

This project is licensed under the MIT License - see the LICENSE file for details.