jlpt-srs/README.MD

A spaced repetition system for Japanese language learning

# JLPT SRS (Spaced Repetition System)

A sophisticated spaced repetition system designed specifically for Japanese language learning and JLPT preparation. The system implements an advanced algorithm similar to SuperMemo/Anki for optimal learning efficiency.

## Features

- **Advanced Spaced Repetition Algorithm**
    - Customizable learning steps
    - Adaptive ease factor adjustments
    - Intelligent interval calculations
    - Support for relearning paths
    - Mature card identification

- **Comprehensive Card Types**
    - Kanji/vocabulary cards with furigana
    - Sentence patterns with detailed breakdowns
    - Grammar notes with importance levels
    - Audio support for proper pronunciation

- **Smart Learning Management**
    - Daily new card limits
    - Review scheduling
    - Leech identification
    - Progress tracking
    - Dynamic difficulty adjustments

## Practical Example

### Setting Up a Study Session

Here's a complete example of implementing a JLPT N4 vocabulary study session:

```typescript
import { SRSManager } from './srsManager';
import { Card, Settings } from './types';

// 1. Define your SRS settings
const jlptSettings: Settings = {
    maxNewCardsPerDay: 10,  // Start with 10 new words per day
    learningSteps: [1, 10], // Review after 1 day, then 10 days
    maxReviewsPerDay: 100,
    graduatingInterval: 1,
    easyInterval: 4,
    startingEase: 2.5,
    easyBonus: 1.3,
    intervalModifier: 1,
    hardInterval: 1.2,
    lapses: {
        relearningSteps: [1, 10],
        minimumInterval: 1,
        leechThreshold: 8,
    }
};

// 2. Create sample vocabulary cards
const sampleCard: Card = {
    id: "verb-taberu",
    phase: "new",
    ease: 2.5,
    interval: 0,
    learning_order: 1,
    word_audio: "taberu.mp3",
    word_to_practice: {
        kanji: "食べる",
        romanji: "taberu",
        kana: "たべる",
        meanings: ["to eat", "to take a meal"],
        furigana: "た",
        difficulty_level: {
            jlpt: "N5",
            wanikani: 1,
            general: 1
        },
        example: "私は寿司を食べる",
        example_romanji: "watashi wa sushi wo taberu"
    },
    sentence: {
        difficulty_level: {
            jlpt: "N5",
            wanikani: 1,
            general: 1
        },
        romanji: "watashi wa mainichi gohan wo taberu",
        furigana: {
            kanji: "私は毎日ご飯を食べる",
            hiragana: "わたしはまいにちごはんをたべる"
        },
        translation: "I eat rice every day",
        meaning: "Expressing daily habits",
        audio: "sentence1.mp3",
        structure_note: "Subject は Object を Verb",
        structure_note_romanji: "Subject wa Object wo Verb",
        breakdown: {
            words: [{
                word: "私",
                form: "noun",
                type: "pronoun",
                meanings: ["I", "me"],
                kanji: "私",
                kana: "わたし",
                root_form: "私",
                group: "pronouns",
                difficulty_level: {
                    jlpt: "N5",
                    wanikani: 1,
                    general: 1
                }
            }]
        }
    },
    grammar_notes: {
        "basic-sentence": {
            importance: 5,
            description: "Basic sentence structure with を particle",
            description_romanji: "Basic sentence structure with wo particle",
            example: "私はりんごを食べる",
            example_romanji: "watashi wa ringo wo taberu"
        }
    }
};

// 3. Initialize the SRS Manager
const manager = new SRSManager(jlptSettings, new Date());

// 4. Start a study session
function startStudySession(cards: Card[]) {
    // Get cards due for review
    const classified = manager.classify(cards);
    
    // Study new cards
    console.log(`New cards to study today: ${classified.new.length}`);
    classified.new.forEach(card => {
        // Display card information
        console.log(`
Word: ${card.word_to_practice.kanji} (${card.word_to_practice.kana})
Meaning: ${card.word_to_practice.meanings.join(', ')}
Example: ${card.sentence.furigana.kanji}
Translation: ${card.sentence.translation}
        `);

        // Process review (simulating user response)
        const updatedCard = manager.processCardReview(card, ReviewAction.Good);
        console.log(`Next review date: ${updatedCard.nextReviewDate}`);
    });

    // Review learning/review cards
    console.log(`Cards in learning: ${classified.learning.length}`);
    console.log(`Cards in review: ${classified.review.length}`);
}

// 5. Track progress
function getStudyStats(cards: Card[]) {
    const summary = manager.getSummary(cards);
    console.log(`
Study Progress:
- Mature cards: ${summary.mature}
- Review cards: ${summary.review}
- Learning cards: ${summary.learning}
- New cards remaining: ${summary.new}
    `);
}

// 6. Example usage in a daily routine
function dailyStudyRoutine(cards: Card[]) {
    // Morning study session
    console.log("=== Morning Study Session ===");
    startStudySession(cards);
    
    // Advance time by 8 hours
    manager.advanceTime(0.33);
    
    // Evening review session
    console.log("=== Evening Review Session ===");
    startStudySession(cards);
    
    // Check daily progress
    getStudyStats(cards);
}

// Run the daily routine
const myCards = [sampleCard]; // Add more cards as needed
dailyStudyRoutine(myCards);
```

### Example Output

```
=== Morning Study Session ===
New cards to study today: 1

Word: 食べる (たべる)
Meaning: to eat, to take a meal
Example: 私は毎日ご飯を食べる
Translation: I eat rice every day

Next review date: 2024-11-16T03:00:00Z

Cards in learning: 0
Cards in review: 0

=== Evening Review Session ===
New cards to study today: 0
Cards in learning: 1
Cards in review: 0

Study Progress:
- Mature cards: 0
- Review cards: 0
- Learning cards: 1
- New cards remaining: 0
```

This example demonstrates:
- Creating and configuring the SRS system
- Structuring vocabulary cards with complete information
- Running daily study sessions
- Tracking progress
- Handling multiple review sessions per day

The card structure includes:
- Kanji and kana forms
- Example sentences with translations
- Grammar notes
- Difficulty levels
- Audio references (for integration with audio files)

## Card Structure

[Rest of the README remains the same...]