studyctl 2.0.0__py3-none-any.whl

studyctl/review_db.py

@@ -0,0 +1,277 @@
+"""Spaced repetition tracking for flashcard and quiz reviews.
+
+Stores per-card review results in the sessions.db SQLite database.
+Uses a simplified SM-2 algorithm for scheduling next reviews.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from .settings import get_db_path
+
+# SM-2 simplified intervals: correct → double interval, wrong → reset to 1
+MIN_EASE = 1.3
+DEFAULT_EASE = 2.5
+
+
+def _get_db() -> Path:
+    """Get sessions.db path from studyctl config."""
+    try:
+        return get_db_path()
+    except Exception:
+        return Path.home() / ".config" / "studyctl" / "sessions.db"
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    """Open a SQLite connection with WAL mode and busy timeout."""
+    conn = sqlite3.connect(db_path)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+    return conn
+
+
+def ensure_tables(db_path: Path | None = None) -> None:
+    """Create card_reviews and review_sessions tables if they don't exist."""
+    path = db_path or _get_db()
+    if not path.exists():
+        return
+
+    with _connect(path) as conn:
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS card_reviews (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                course TEXT NOT NULL,
+                card_type TEXT NOT NULL,
+                card_hash TEXT NOT NULL,
+                correct BOOLEAN NOT NULL,
+                reviewed_at TEXT NOT NULL,
+                ease_factor REAL DEFAULT 2.5,
+                interval_days INTEGER DEFAULT 1,
+                next_review TEXT,
+                response_time_ms INTEGER
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_card_reviews_next
+            ON card_reviews(course, next_review)
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_card_reviews_hash
+            ON card_reviews(card_hash)
+        """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS review_sessions (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                course TEXT NOT NULL,
+                mode TEXT NOT NULL,
+                total INTEGER NOT NULL,
+                correct INTEGER NOT NULL,
+                duration_seconds INTEGER,
+                started_at TEXT NOT NULL,
+                finished_at TEXT
+            )
+        """)
+
+
+def record_card_review(
+    course: str,
+    card_type: str,
+    card_hash: str,
+    correct: bool,
+    response_time_ms: int | None = None,
+    db_path: Path | None = None,
+) -> None:
+    """Record a single card review and update spaced repetition schedule."""
+    path = db_path or _get_db()
+    ensure_tables(path)
+
+    with _connect(path) as conn:
+        now = datetime.now(UTC).isoformat()
+
+        # Get previous review for this card
+        row = conn.execute(
+            "SELECT ease_factor, interval_days FROM card_reviews "
+            "WHERE card_hash = ? ORDER BY reviewed_at DESC LIMIT 1",
+            (card_hash,),
+        ).fetchone()
+
+        if row:
+            ease, interval = row
+        else:
+            ease, interval = DEFAULT_EASE, 1
+
+        # SM-2 simplified update
+        if correct:
+            interval = max(1, int(interval * ease))
+            ease = min(ease + 0.1, 3.0)
+        else:
+            interval = 1
+            ease = max(ease - 0.2, MIN_EASE)
+
+        next_review = (datetime.now(UTC) + timedelta(days=interval)).strftime("%Y-%m-%d")
+
+        conn.execute(
+            "INSERT INTO card_reviews "
+            "(course, card_type, card_hash, correct, reviewed_at, "
+            "ease_factor, interval_days, next_review, response_time_ms) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                course,
+                card_type,
+                card_hash,
+                correct,
+                now,
+                ease,
+                interval,
+                next_review,
+                response_time_ms,
+            ),
+        )
+
+
+def record_session(
+    course: str,
+    mode: str,
+    total: int,
+    correct: int,
+    duration_seconds: int | None = None,
+    db_path: Path | None = None,
+) -> None:
+    """Record a complete review session."""
+    path = db_path or _get_db()
+    ensure_tables(path)
+
+    with _connect(path) as conn:
+        now = datetime.now(UTC).isoformat()
+        conn.execute(
+            "INSERT INTO review_sessions "
+            "(course, mode, total, correct, duration_seconds, started_at, finished_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (course, mode, total, correct, duration_seconds, now, now),
+        )
+
+
+@dataclass
+class CardProgress:
+    card_hash: str
+    last_correct: bool
+    ease_factor: float
+    interval_days: int
+    next_review: str
+    review_count: int
+
+
+def get_due_cards(course: str, db_path: Path | None = None) -> list[CardProgress]:
+    """Get cards due for review (next_review <= today)."""
+    path = db_path or _get_db()
+    if not path.exists():
+        return []
+
+    ensure_tables(path)
+    with _connect(path) as conn:
+        today = datetime.now(UTC).strftime("%Y-%m-%d")
+
+        rows = conn.execute(
+            """
+            WITH latest AS (
+                SELECT card_hash, correct, ease_factor, interval_days, next_review,
+                       COUNT(*) OVER (PARTITION BY card_hash) as review_count,
+                       ROW_NUMBER() OVER (PARTITION BY card_hash ORDER BY reviewed_at DESC) as rn
+                FROM card_reviews
+                WHERE course = ?
+            )
+            SELECT card_hash, correct, ease_factor, interval_days, next_review, review_count
+            FROM latest
+            WHERE rn = 1 AND next_review <= ?
+            ORDER BY next_review ASC
+            """,
+            (course, today),
+        ).fetchall()
+
+    return [
+        CardProgress(
+            card_hash=r[0],
+            last_correct=bool(r[1]),
+            ease_factor=r[2],
+            interval_days=r[3],
+            next_review=r[4],
+            review_count=r[5],
+        )
+        for r in rows
+    ]
+
+
+def get_wrong_hashes(course: str, db_path: Path | None = None) -> set[str]:
+    """Get card hashes that were incorrect in the most recent session."""
+    path = db_path or _get_db()
+    if not path.exists():
+        return set()
+
+    ensure_tables(path)
+    with _connect(path) as conn:
+        # Find the most recent session's reviewed_at range
+        last_session = conn.execute(
+            "SELECT started_at FROM review_sessions "
+            "WHERE course = ? ORDER BY started_at DESC LIMIT 1",
+            (course,),
+        ).fetchone()
+
+        if not last_session:
+            return set()
+
+        rows = conn.execute(
+            "SELECT DISTINCT card_hash FROM card_reviews "
+            "WHERE course = ? AND correct = 0 AND reviewed_at >= ?",
+            (course, last_session[0]),
+        ).fetchall()
+
+    return {r[0] for r in rows}
+
+
+def get_course_stats(course: str, db_path: Path | None = None) -> dict:
+    """Get summary statistics for a course."""
+    path = db_path or _get_db()
+    if not path.exists():
+        return {"total_reviews": 0, "unique_cards": 0, "due_today": 0, "mastered": 0}
+
+    ensure_tables(path)
+    with _connect(path) as conn:
+        today = datetime.now(UTC).strftime("%Y-%m-%d")
+
+        total = conn.execute(
+            "SELECT COUNT(*) FROM card_reviews WHERE course = ?", (course,)
+        ).fetchone()[0]
+
+        unique = conn.execute(
+            "SELECT COUNT(DISTINCT card_hash) FROM card_reviews WHERE course = ?", (course,)
+        ).fetchone()[0]
+
+        due = conn.execute(
+            "SELECT COUNT(DISTINCT card_hash) FROM card_reviews "
+            "WHERE course = ? AND next_review <= ?",
+            (course, today),
+        ).fetchone()[0]
+
+        # Mastered = interval > 30 days
+        mastered = conn.execute(
+            """
+            SELECT COUNT(DISTINCT card_hash) FROM card_reviews cr1
+            WHERE course = ? AND interval_days > 30
+            AND reviewed_at = (
+                SELECT MAX(reviewed_at) FROM card_reviews cr2
+                WHERE cr2.card_hash = cr1.card_hash
+            )
+            """,
+            (course,),
+        ).fetchone()[0]
+
+    return {
+        "total_reviews": total,
+        "unique_cards": unique,
+        "due_today": due,
+        "mastered": mastered,
+    }

studyctl/review_loader.py

@@ -0,0 +1,375 @@
+"""Self-contained flashcard and quiz JSON loader.
+
+Reads the same JSON format generated by pdf-by-chapters from-obsidian.
+No cross-package imports -- the JSON format IS the contract.
+
+Flashcard JSON shape
+--------------------
+::
+
+    {
+        "title": str,          # REQUIRED -- deck/chapter display name
+        "cards": [             # REQUIRED -- list of card objects
+            {
+                "front": str,  # REQUIRED -- question or prompt
+                "back":  str   # REQUIRED -- answer or explanation
+            },
+            ...
+        ]
+    }
+
+Files matched by glob: ``*flashcards.json``
+
+Quiz JSON shape
+---------------
+::
+
+    {
+        "title": str,                  # REQUIRED -- quiz display name
+        "questions": [                 # REQUIRED -- list of question objects
+            {
+                "question": str,       # REQUIRED -- the question text
+                "hint":     str,       # optional -- hint shown on request
+                "answerOptions": [     # REQUIRED -- list of option objects (>=2)
+                    {
+                        "text":      str,   # REQUIRED -- option display text
+                        "isCorrect": bool,  # optional -- true for correct answer
+                                            #             (default false)
+                        "rationale": str    # optional -- explanation shown after
+                                            #             answering
+                    },
+                    ...
+                ]
+            },
+            ...
+        ]
+    }
+
+Files matched by glob: ``*quiz.json``
+
+Validation behaviour
+--------------------
+Files that fail JSON parsing or are missing required keys are skipped with a
+warning logged via ``logging.getLogger(__name__)``. This keeps the loader
+resilient to partial / in-progress content while giving clear diagnostics.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import random
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Flashcard:
+    front: str
+    back: str
+    source: str = ""
+
+    @property
+    def card_hash(self) -> str:
+        """Stable hash for spaced repetition tracking.
+
+        Truncated to 16 hex chars (64 bits) because:
+        - Display-friendly in logs, TUI, and DB columns
+        - Sufficient collision resistance for a study app (~4 billion cards
+          before a 50% birthday-collision probability)
+        - MUST NOT be changed: existing SM-2 spaced repetition history in
+          sessions.db is keyed on this value; altering the length would
+          orphan all stored review progress
+        """
+        return hashlib.sha256(self.front.encode()).hexdigest()[:16]
+
+
+@dataclass
+class QuizOption:
+    text: str
+    is_correct: bool
+    rationale: str = ""
+
+
+@dataclass
+class QuizQuestion:
+    question: str
+    options: list[QuizOption]
+    hint: str = ""
+    source: str = ""
+
+    @property
+    def card_hash(self) -> str:
+        """Stable hash for spaced repetition tracking.
+
+        Truncated to 16 hex chars (64 bits) because:
+        - Display-friendly in logs, TUI, and DB columns
+        - Sufficient collision resistance for a study app (~4 billion cards
+          before a 50% birthday-collision probability)
+        - MUST NOT be changed: existing SM-2 spaced repetition history in
+          sessions.db is keyed on this value; altering the length would
+          orphan all stored review progress
+        """
+        return hashlib.sha256(self.question.encode()).hexdigest()[:16]
+
+
+@dataclass
+class ReviewResult:
+    total: int = 0
+    correct: int = 0
+    incorrect: int = 0
+    skipped: int = 0
+    wrong_hashes: set[str] = field(default_factory=set)
+
+    @property
+    def score_pct(self) -> float:
+        attempted = self.correct + self.incorrect
+        return (self.correct / attempted * 100) if attempted > 0 else 0.0
+
+
+def load_flashcards(directory: Path) -> list[Flashcard]:
+    """Load all flashcard JSON files from a directory."""
+    cards: list[Flashcard] = []
+    for path in sorted(directory.glob("*flashcards.json")):
+        try:
+            data = json.loads(path.read_text())
+        except json.JSONDecodeError as exc:
+            logger.warning("Skipping %s: invalid JSON (%s)", path.name, exc)
+            continue
+
+        if not isinstance(data, dict):
+            logger.warning(
+                "Skipping %s: expected JSON object, got %s", path.name, type(data).__name__
+            )
+            continue
+
+        if "cards" not in data:
+            logger.warning("Skipping %s: missing required 'cards' key", path.name)
+            continue
+
+        if not isinstance(data["cards"], list):
+            logger.warning(
+                "Skipping %s: 'cards' must be a list, got %s",
+                path.name,
+                type(data["cards"]).__name__,
+            )
+            continue
+
+        source = data.get("title", path.stem)
+        for i, card in enumerate(data["cards"]):
+            if not isinstance(card, dict):
+                logger.warning(
+                    "Skipping card %d in %s: expected object, got %s",
+                    i,
+                    path.name,
+                    type(card).__name__,
+                )
+                continue
+            if "front" not in card:
+                logger.warning(
+                    "Skipping card %d in %s: missing required 'front' field", i, path.name
+                )
+                continue
+            if "back" not in card:
+                logger.warning(
+                    "Skipping card %d in %s: missing required 'back' field", i, path.name
+                )
+                continue
+            try:
+                cards.append(Flashcard(front=card["front"], back=card["back"], source=source))
+            except (TypeError, ValueError) as exc:
+                logger.warning("Skipping card %d in %s: %s", i, path.name, exc)
+                continue
+
+    return cards
+
+
+def load_quizzes(directory: Path) -> list[QuizQuestion]:
+    """Load all quiz JSON files from a directory."""
+    questions: list[QuizQuestion] = []
+    for path in sorted(directory.glob("*quiz.json")):
+        try:
+            data = json.loads(path.read_text())
+        except json.JSONDecodeError as exc:
+            logger.warning("Skipping %s: invalid JSON (%s)", path.name, exc)
+            continue
+
+        if not isinstance(data, dict):
+            logger.warning(
+                "Skipping %s: expected JSON object, got %s", path.name, type(data).__name__
+            )
+            continue
+
+        if "questions" not in data:
+            logger.warning("Skipping %s: missing required 'questions' key", path.name)
+            continue
+
+        if not isinstance(data["questions"], list):
+            logger.warning(
+                "Skipping %s: 'questions' must be a list, got %s",
+                path.name,
+                type(data["questions"]).__name__,
+            )
+            continue
+
+        source = data.get("title", path.stem)
+        for i, q in enumerate(data["questions"]):
+            if not isinstance(q, dict):
+                logger.warning(
+                    "Skipping question %d in %s: expected object, got %s",
+                    i,
+                    path.name,
+                    type(q).__name__,
+                )
+                continue
+            if "question" not in q:
+                logger.warning(
+                    "Skipping question %d in %s: missing required 'question' field", i, path.name
+                )
+                continue
+
+            answer_options = q.get("answerOptions", [])
+            if not isinstance(answer_options, list):
+                logger.warning(
+                    "Skipping question %d in %s: 'answerOptions' must be a list, got %s",
+                    i,
+                    path.name,
+                    type(answer_options).__name__,
+                )
+                continue
+
+            options: list[QuizOption] = []
+            for j, opt in enumerate(answer_options):
+                if not isinstance(opt, dict):
+                    logger.warning(
+                        "Skipping option %d of question %d in %s: expected object, got %s",
+                        j,
+                        i,
+                        path.name,
+                        type(opt).__name__,
+                    )
+                    continue
+                if "text" not in opt:
+                    logger.warning(
+                        "Skipping option %d of question %d in %s: missing required 'text' field",
+                        j,
+                        i,
+                        path.name,
+                    )
+                    continue
+                options.append(
+                    QuizOption(
+                        text=opt["text"],
+                        is_correct=opt.get("isCorrect", False),
+                        rationale=opt.get("rationale", ""),
+                    )
+                )
+
+            try:
+                questions.append(
+                    QuizQuestion(
+                        question=q["question"],
+                        options=options,
+                        hint=q.get("hint", ""),
+                        source=source,
+                    )
+                )
+            except (TypeError, ValueError) as exc:
+                logger.warning("Skipping question %d in %s: %s", i, path.name, exc)
+                continue
+
+    return questions
+
+
+_GENERIC_DIR_NAMES = {"downloads", "content", "data", "files", "output", "generated"}
+
+
+def _course_name(directory: Path) -> str:
+    """Derive a display name from a directory path.
+
+    Uses the parent name when the directory has a generic name like 'downloads'.
+    """
+    name = directory.name
+    if name.lower() in _GENERIC_DIR_NAMES:
+        return directory.parent.name
+    return name
+
+
+def discover_directories(config_dirs: list[str] | None = None) -> list[tuple[str, Path]]:
+    """Discover course directories with flashcard/quiz content.
+
+    Returns list of (course_name, directory_path) tuples.
+    Searches configured directories and their subdirectories.
+    """
+    if not config_dirs:
+        return []
+
+    courses: list[tuple[str, Path]] = []
+    for dir_str in config_dirs:
+        base = Path(dir_str).expanduser()
+        if not base.is_dir():
+            continue
+
+        # Check if this directory itself has content
+        if _has_review_content(base):
+            courses.append((_course_name(base), base))
+            continue
+
+        # Check subdirectories (e.g. downloads/flashcards/)
+        downloads = base / "downloads"
+        if downloads.is_dir() and _has_review_content(downloads):
+            courses.append((_course_name(base), downloads))
+            continue
+
+        # Check immediate children
+        for child in sorted(base.iterdir()):
+            if child.is_dir() and _has_review_content(child):
+                courses.append((_course_name(child), child))
+
+    return courses
+
+
+def _has_review_content(directory: Path) -> bool:
+    """Check if a directory has flashcard or quiz JSON files."""
+    fc_dir = directory / "flashcards"
+    quiz_dir = directory / "quizzes"
+
+    if fc_dir.is_dir() and list(fc_dir.glob("*flashcards.json")):
+        return True
+    if quiz_dir.is_dir() and list(quiz_dir.glob("*quiz.json")):
+        return True
+    if list(directory.glob("*flashcards.json")):
+        return True
+    return bool(list(directory.glob("*quiz.json")))
+
+
+def find_content_dirs(directory: Path) -> tuple[Path | None, Path | None]:
+    """Find flashcard and quiz subdirectories within a directory."""
+    fc_dir: Path | None = None
+    quiz_dir: Path | None = None
+
+    fc_sub = directory / "flashcards"
+    if fc_sub.is_dir() and list(fc_sub.glob("*-flashcards.json")):
+        fc_dir = fc_sub
+    elif list(directory.glob("*flashcards.json")):
+        fc_dir = directory
+
+    quiz_sub = directory / "quizzes"
+    if quiz_sub.is_dir() and list(quiz_sub.glob("*-quiz.json")):
+        quiz_dir = quiz_sub
+    elif list(directory.glob("*quiz.json")):
+        quiz_dir = directory
+
+    return fc_dir, quiz_dir
+
+
+def shuffle_items(items: list, enabled: bool = True) -> list:
+    """Shuffle a list if enabled."""
+    if enabled:
+        result = list(items)
+        random.shuffle(result)
+        return result
+    return items