flashcard-generator

name	flashcard-generator
description	Generate flashcards, quizzes, and study materials from notes or topics using spaced repetition principles.

Flashcard & Quiz Generator

Generate study materials grounded in memory science. Follow Wozniak's formulation rules, schedule with SM-2, export to Anki via genanki.

When to Use

• User pastes notes/textbook content to convert to cards, needs exam prep, or wants an Anki deck

When NOT to Use

• In-depth research (deep-research), data analysis (data-analysis)

Why Spaced Repetition Works

Ebbinghaus (1885) showed memory decays as R = e^(-t/S) where S is memory stability — without review, ~50-70% of new information is gone within 24 hours. The curve was replicated in 2015 (Murre & Dros, PLOS ONE). Each successful recall increases S, flattening the curve. The core insight: reviewing just before you'd forget is the most efficient moment to review. Active recall (retrieving the answer) builds stability far more than passive re-reading — this is why cards beat highlighting.

Card Formulation: Wozniak's 20 Rules

Piotr Wozniak (SuperMemo creator; Anki forked his SM-2 algorithm) published the canonical rules in 1999 at supermemo.com. The ones that matter most for card generation:

Rule 1-2: Understand before you memorize. Don't make cards for material the user hasn't grasped yet. Cards reinforce; they don't teach.

Rule 4: Minimum Information Principle — the single most important rule. One atomic fact per card. Complex cards get forgotten as a unit — if any part fails, the whole card resets. Split aggressively.

• Bad: Q: What are the three branches of US government and what does each do? (6 facts, fails together)
• Good: Six cards. Q: Which branch of US government writes laws? A: Legislative × each branch × each function.

Rule 5: Cloze deletion is the fastest path from prose to cards. Take a sentence, blank one term. Beginners who struggle with minimum-information should default to cloze.

• Source: TCP guarantees ordered delivery; UDP does not.
• Cards: {{c1::TCP}} guarantees ordered delivery; {{c2::UDP}} does not. → 2 cards from one sentence

Rule 9-10: Avoid sets and enumerations. "List all 7 OSI layers" is a nightmare card — high failure rate, painful reviews. Instead, use overlapping cloze: one sentence with the full list, generate N cards each blanking one item. The redundancy is intentional — it's extra cards, not extra info per card.

Rule 11: Combat interference. Similar cards confuse each other (affect vs effect, port 80 vs 443). Add disambiguating context: Q: [web, unencrypted] Default HTTP port? A: 80.

Rule 14: Personalize. Q: What's O(n log n)? A: Merge sort — like the algorithm you botched in the Stripe interview sticks better than the abstract definition.

The diagnostic: If a card's ease factor drops below 1.3 in review, the card is malformed, not hard. Rewrite it, don't grind it.

Card Types

Type	Use for	Example
Basic Q→A	Single facts	Q: Capital of Mongolia? A: Ulaanbaatar
Cloze	Converting prose fast; lists	The {{c1::mitochondria}} produces {{c2::ATP}} via {{c3::oxidative phosphorylation}} → 3 cards
Reversed	Bidirectional recall (vocab)	Generates both fr→en and en→fr
Application	Understanding, not recall	Q: Revenue +20%, profit −5%. Why? A: Costs grew faster than revenue
Image occlusion	Anatomy, diagrams, maps	Blank one label on a diagram per card (Wozniak rule 8)

Mix Bloom's levels: ~40% remember (basic/cloze), ~30% understand, ~30% apply/analyze. Pure recall decks feel productive but fail on exams that test transfer.

SM-2 Scheduling (What Anki Runs)

Wozniak's 1987 algorithm. Each card tracks three values: repetition count n, ease factor EF (starts at 2.5), interval I in days. After each review, grade 0-5:

if grade >= 3:               # correct
    if n == 0: I = 1
    elif n == 1: I = 6
    else: I = round(I * EF)   # exponential growth
    n += 1
else:                         # forgot
    n = 0; I = 1              # reset interval, keep EF

EF += 0.1 - (5-grade) * (0.08 + (5-grade)*0.02)
EF = max(EF, 1.3)             # floor — below this, card is malformed

Grade 5 → EF +0.10. Grade 4 → no change. Grade 3 → EF −0.14. A card you always rate "good" (4) with EF 2.5 goes: 1 → 6 → 15 → 38 → 94 days. FSRS (Anki 23.10+) is the ML successor — fits a personal forgetting curve, ~20-30% fewer reviews for same retention. Mention it; default to SM-2 for simplicity.

Export to Anki: genanki

pip install genanki (github.com/kerrickstaley/genanki). Generates .apkg files that import directly via File → Import.

import genanki, random

# Generate these ONCE, then hardcode — stable IDs let users re-import updates
MODEL_ID = random.randrange(1 << 30, 1 << 31)  # e.g. 1607392319
DECK_ID  = random.randrange(1 << 30, 1 << 31)

basic = genanki.Model(MODEL_ID, 'Basic',
    fields=[{'name': 'Q'}, {'name': 'A'}],
    templates=[{'name': 'Card 1', 'qfmt': '{{Q}}',
                'afmt': '{{FrontSide}}<hr id="answer">{{A}}'}],
    css='.card { font-family: Arial; font-size: 20px; text-align: center; }')

deck = genanki.Deck(DECK_ID, 'Biology :: Cell Structure')
deck.add_note(genanki.Note(model=basic,
    fields=['What organelle produces ATP?', 'Mitochondria']))

# Cloze uses built-in model — second field required (can be empty) since 0.13.0
deck.add_note(genanki.Note(model=genanki.builtin_models.CLOZE_MODEL,
    fields=['The {{c1::mitochondria}} produces {{c2::ATP}}', '']))

genanki.Package(deck).write_to_file('cells.apkg')

Gotchas: Fields are HTML — html.escape() any user content with <, >, &. For images/audio, set package.media_files = ['diagram.png'] and reference by basename only in the field: <img src="diagram.png"> (paths break). Stable GUIDs let re-imports update cards in place — subclass Note and override guid to hash only the question field.

Quizlet/CSV fallback: Tab-separated, one card per line: question\tanswer\n. Quizlet imports directly. Also works for Anki's File → Import → Text.

Output: Always Build a Web App

Every flashcard generation MUST produce an interactive web app as the primary output. Do not output cards as plain text or markdown — always build a React + Vite single-page app with two modes the user can switch between:

Mode 1: Flashcard Review

1. Card display — show front of card, flip to back on click or spacebar
2. SM-2 grading — four buttons: Again (1), Hard (3), Good (4), Easy (5), wired to the SM-2 algorithm above
3. Spaced repetition queue — localStorage persistence for {cardId: {n, EF, I, due}}. Sort queue by due date. Cards due today appear first.
4. Session stats — cards reviewed, accuracy %, cards due tomorrow, total remaining
5. Card type support — render Basic Q→A, Cloze (hide blanked terms), and Reversed cards correctly
6. Flip animation — CSS 3D transform, keyboard shortcuts (Space to flip, 1/2/3/4 for grading)

Mode 2: AI Quiz

An AI-powered quiz mode that generates and grades questions:

1. Quiz setup — user picks a topic (or all topics) and number of questions (5, 10, 20, custom)
2. Question generation — use AI integrations to generate N questions from the card material. Mix question types: multiple choice, short answer, and true/false. Questions should test understanding and application, not just recall.
3. Answer & grade — user answers each question, then AI grades the response with a score and explanation of what was right/wrong
4. Quiz results — summary screen with overall score, per-question breakdown, and which topics need more work
5. Weak spot feedback — highlight topics where the user scored lowest and suggest reviewing those flashcards

UI/UX Requirements

• Tab or toggle to switch between Flashcard and Quiz modes
• Clean, focused design — one card or question centered on screen, no clutter
• Mobile-friendly — responsive layout, touch targets
• Topic/deck selector — filter by topic in both modes
• Progress indicator — card counter in flashcard mode, question progress bar in quiz mode

Best Practices

1. Minimum information principle trumps everything — when in doubt, split the card
2. Cloze is the default for prose — fastest path from notes to reviewable cards
3. Never make set-enumeration cards — "list all X" → overlapping cloze instead
4. 30 great cards > 100 mediocre ones — review burden compounds; every bad card costs minutes over months
5. Cap new cards at ~20/day — the review debt from 100 new cards/day becomes unsustainable by week 3

Limitations

• Cannot read existing .apkg files (genanki is write-only); cannot sync to AnkiWeb
• Cannot track review history across sessions unless building a persistent app
• Verify generated content for specialized domains — confident-sounding wrong cards are worse than no cards