studyctl 2.0.0__py3-none-any.whl

studyctl/tui/study_cards.py

@@ -0,0 +1,396 @@
+"""Interactive flashcard and quiz review tab for the studyctl TUI.
+
+Provides keyboard-driven study with spaced repetition tracking
+and optional voice output via study-speak.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+from enum import StrEnum
+from typing import TYPE_CHECKING, ClassVar
+
+try:
+    from textual.binding import Binding
+    from textual.containers import Center, Horizontal
+    from textual.reactive import reactive
+    from textual.widget import Widget
+    from textual.widgets import Button, Static
+except ImportError as _exc:
+    raise ImportError("The TUI requires 'textual'. Install: pip install studyctl[tui]") from _exc
+
+if TYPE_CHECKING:
+    from textual.app import ComposeResult
+
+from studyctl.review_db import record_card_review, record_session
+from studyctl.review_loader import (
+    Flashcard,
+    QuizQuestion,
+    ReviewResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class StudyMode(StrEnum):
+    """Tracks whether the user is in a normal or retry study session."""
+
+    NORMAL = "normal"
+    RETRY = "retry"
+
+
+class CardPanel(Static):
+    """Displays a flashcard or quiz question with flip support."""
+
+    revealed = reactive(False)
+
+    def __init__(self, **kwargs: object) -> None:
+        super().__init__(**kwargs)
+        self._front = ""
+        self._back = ""
+
+    def set_card(self, front: str, back: str) -> None:
+        self._front = front
+        self._back = back
+        self.revealed = False
+        self.update(self._front)
+
+    def flip(self) -> None:
+        self.revealed = not self.revealed
+        self.update(self._back if self.revealed else self._front)
+
+
+class StudyCardsTab(Widget):
+    """Interactive flashcard and quiz review widget."""
+
+    can_focus = True
+
+    DEFAULT_CSS = """
+    StudyCardsTab {
+        layout: vertical;
+        padding: 1 2;
+    }
+    #card-panel {
+        height: auto;
+        min-height: 5;
+        padding: 1 2;
+        border: round $accent;
+        margin: 1 0;
+    }
+    #card-panel.revealed {
+        border: round $success;
+    }
+    #score-bar {
+        height: 3;
+        dock: bottom;
+        margin-top: 1;
+    }
+    #progress-label {
+        text-align: center;
+        margin: 1 0;
+    }
+    #status-label {
+        text-align: center;
+        color: $text-muted;
+    }
+    #voice-label {
+        text-align: right;
+        color: $text-muted;
+    }
+    .score-btn {
+        margin: 0 1;
+    }
+    """
+
+    BINDINGS: ClassVar[list[Binding]] = [
+        Binding("space", "flip", "Flip / Submit"),
+        Binding("y", "mark_correct", "Correct"),
+        Binding("n", "mark_incorrect", "Incorrect"),
+        Binding("s", "skip_card", "Skip"),
+        Binding("h", "show_hint", "Hint"),
+        Binding("v", "toggle_voice", "Voice"),
+        Binding("r", "retry_wrong", "Retry Wrong"),
+    ]
+
+    current_index = reactive(0)
+    voice_enabled = reactive(False)
+    _study_mode: reactive[StudyMode] = reactive(StudyMode.NORMAL, bindings=True)
+
+    def __init__(
+        self,
+        cards: list[Flashcard | QuizQuestion],
+        course_name: str = "",
+        mode: str = "flashcards",
+        **kwargs: object,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._all_cards = list(cards)
+        self._cards = cards
+        self._course = course_name
+        self._mode = mode
+        self._result = ReviewResult(total=len(cards))
+        self._start_time = time.monotonic()
+        self._card_start_time = time.monotonic()
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        if action == "retry_wrong":
+            return bool(self._result.wrong_hashes) and self._study_mode is not StudyMode.RETRY
+        return True
+
+    def compose(self) -> ComposeResult:
+        yield Static(
+            f"[bold]{self._course}[/bold] — {self._mode} ({len(self._cards)} items)",
+            id="status-label",
+        )
+        voice_text = "Voice: ON" if self.voice_enabled else "Voice: OFF (v to toggle)"
+        yield Static(voice_text, id="voice-label")
+        yield CardPanel(id="card-panel")
+        yield Static("", id="progress-label")
+        with Center(), Horizontal(id="score-bar"):
+            yield Button(
+                "Know (y)",
+                variant="success",
+                id="btn-correct",
+                classes="score-btn",
+            )
+            yield Button(
+                "Don't Know (n)",
+                variant="error",
+                id="btn-incorrect",
+                classes="score-btn",
+            )
+            yield Button(
+                "Skip (s)",
+                variant="default",
+                id="btn-skip",
+                classes="score-btn",
+            )
+
+    def on_mount(self) -> None:
+        self.focus()
+        self._show_current_card()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "btn-correct":
+            self.action_mark_correct()
+        elif event.button.id == "btn-incorrect":
+            self.action_mark_incorrect()
+        elif event.button.id == "btn-skip":
+            self.action_skip_card()
+
+    def _show_current_card(self) -> None:
+        if self.current_index >= len(self._cards):
+            self._show_summary()
+            return
+
+        card = self._cards[self.current_index]
+        panel = self.query_one("#card-panel", CardPanel)
+        self._card_start_time = time.monotonic()
+
+        if isinstance(card, Flashcard):
+            panel.set_card(
+                f"[bold]Q:[/bold] {card.front}\n\n[dim]Press Space to reveal answer[/dim]",
+                f"[bold]A:[/bold] {card.back}",
+            )
+        else:
+            # Quiz question
+            lines = [f"[bold]Q:[/bold] {card.question}\n"]
+            letters = "abcdefghij"
+            for j, opt in enumerate(card.options):
+                lines.append(f"  [bold]{letters[j]})[/bold] {opt.text}")
+            lines.append("\n[dim]Press Space to reveal answer[/dim]")
+            panel.set_card(
+                "\n".join(lines),
+                self._format_quiz_answer(card),
+            )
+
+        # Speak the question if voice enabled
+        if self.voice_enabled:
+            text = card.front if isinstance(card, Flashcard) else card.question
+            self._speak(text)
+
+        retry_tag = " (Retry)" if self._study_mode is StudyMode.RETRY else ""
+        progress = f"Card {self.current_index + 1}/{len(self._cards)}{retry_tag}"
+        if self._result.correct + self._result.incorrect > 0:
+            progress += f"  |  Score: {self._result.score_pct:.0f}%"
+        self.query_one("#progress-label", Static).update(progress)
+
+    def _format_quiz_answer(self, q: QuizQuestion) -> str:
+        letters = "abcdefghij"
+        correct_idx = next((i for i, o in enumerate(q.options) if o.is_correct), 0)
+        correct_opt = q.options[correct_idx]
+        lines = [f"[green bold]Answer: {letters[correct_idx]})[/green bold] {correct_opt.text}"]
+        if correct_opt.rationale:
+            lines.append(f"\n[dim]{correct_opt.rationale}[/dim]")
+        return "\n".join(lines)
+
+    def _record_answer(self, correct: bool) -> None:
+        card = self._cards[self.current_index]
+        elapsed_ms = int((time.monotonic() - self._card_start_time) * 1000)
+
+        if correct:
+            self._result.correct += 1
+        else:
+            self._result.incorrect += 1
+            self._result.wrong_hashes.add(card.card_hash)
+
+        # Record to DB (skip SM-2 during retry)
+        if self._study_mode is not StudyMode.RETRY:
+            card_type = "flashcard" if isinstance(card, Flashcard) else "quiz"
+            try:
+                record_card_review(
+                    course=self._course,
+                    card_type=card_type,
+                    card_hash=card.card_hash,
+                    correct=correct,
+                    response_time_ms=elapsed_ms,
+                )
+            except (sqlite3.Error, OSError) as exc:
+                logger.debug("Failed to record card review: %s", exc)
+
+        self.current_index += 1
+        self._show_current_card()
+
+    def _show_summary(self) -> None:
+        duration = int(time.monotonic() - self._start_time)
+        attempted = self._result.correct + self._result.incorrect
+        pct = self._result.score_pct
+
+        if pct >= 80:
+            grade = "[green]Excellent[/green]"
+        elif pct >= 60:
+            grade = "[yellow]Good[/yellow]"
+        else:
+            grade = "[red]Needs review[/red]"
+
+        wrong_count = len(self._result.wrong_hashes)
+        summary = [
+            "[bold]Session Complete![/bold]",
+            "",
+            f"  Score: {self._result.correct}/{attempted} ({pct:.0f}%) — {grade}",
+            f"  Skipped: {self._result.skipped}",
+            f"  Duration: {duration // 60}m {duration % 60}s",
+        ]
+        if wrong_count and self._study_mode is not StudyMode.RETRY:
+            summary.append(
+                f"\n  [yellow]{wrong_count} cards to review again — press r to retry[/yellow]"
+            )
+
+        panel = self.query_one("#card-panel", CardPanel)
+        panel.update("\n".join(summary))
+
+        # Hide score buttons
+        for btn_id in ("btn-correct", "btn-incorrect", "btn-skip"):
+            self.query_one(f"#{btn_id}", Button).display = False
+
+        hint = "[bold]Press q to return[/bold]"
+        if self._result.wrong_hashes and self._study_mode is not StudyMode.RETRY:
+            hint = "[bold]Press r to retry wrong, q to return[/bold]"
+        self.query_one("#progress-label", Static).update(hint)
+
+        # Record session
+        try:
+            record_session(
+                course=self._course,
+                mode=self._mode,
+                total=self._result.total,
+                correct=self._result.correct,
+                duration_seconds=duration,
+            )
+        except (sqlite3.Error, OSError) as exc:
+            logger.debug("Failed to record session: %s", exc)
+
+    def _speak(self, text: str) -> None:
+        """Speak text via study-speak (non-blocking, best-effort)."""
+        try:
+            from agent_session_tools.speak import (
+                _get_tts_config,
+                _speak_kokoro,
+            )
+
+            cfg = _get_tts_config()
+            voice = cfg.get("voice", "am_michael")
+            speed = cfg.get("speed", 1.0)
+            import threading
+
+            threading.Thread(
+                target=_speak_kokoro,
+                args=(text,),
+                kwargs={"voice": voice, "speed": speed},
+                daemon=True,
+            ).start()
+        except (ImportError, OSError, RuntimeError) as exc:
+            logger.debug("Voice unavailable: %s", exc)
+
+    # --- Actions ---
+
+    def action_flip(self) -> None:
+        panel = self.query_one("#card-panel", CardPanel)
+        if not panel.revealed:
+            panel.flip()
+            panel.add_class("revealed")
+            if self.voice_enabled and self.current_index < len(self._cards):
+                card = self._cards[self.current_index]
+                text = card.back if isinstance(card, Flashcard) else ""
+                if text:
+                    self._speak(text)
+
+    def action_mark_correct(self) -> None:
+        panel = self.query_one("#card-panel", CardPanel)
+        if panel.revealed:
+            panel.remove_class("revealed")
+            self._record_answer(correct=True)
+
+    def action_mark_incorrect(self) -> None:
+        panel = self.query_one("#card-panel", CardPanel)
+        if panel.revealed:
+            panel.remove_class("revealed")
+            self._record_answer(correct=False)
+
+    def action_skip_card(self) -> None:
+        self._result.skipped += 1
+        panel = self.query_one("#card-panel", CardPanel)
+        panel.remove_class("revealed")
+        self.current_index += 1
+        self._show_current_card()
+
+    def action_show_hint(self) -> None:
+        if self.current_index >= len(self._cards):
+            return
+        card = self._cards[self.current_index]
+        if isinstance(card, QuizQuestion) and card.hint:
+            self.notify(f"Hint: {card.hint}", title="Hint")
+
+    def action_toggle_voice(self) -> None:
+        self.voice_enabled = not self.voice_enabled
+        label = self.query_one("#voice-label", Static)
+        if self.voice_enabled:
+            label.update("[green]Voice: ON[/green]")
+            self.notify("Voice enabled")
+        else:
+            label.update("Voice: OFF (v to toggle)")
+            self.notify("Voice disabled")
+
+    def action_retry_wrong(self) -> None:
+        """Retry only the incorrectly answered cards."""
+        if not self._result.wrong_hashes or self._study_mode is StudyMode.RETRY:
+            return
+
+        wrong = self._result.wrong_hashes
+        retry_cards = [c for c in self._all_cards if c.card_hash in wrong]
+        if not retry_cards:
+            return
+
+        self._cards = retry_cards
+        self._result = ReviewResult(total=len(retry_cards))
+        self._study_mode = StudyMode.RETRY
+        self.current_index = 0
+        self._start_time = time.monotonic()
+
+        # Re-show score buttons
+        for btn_id in ("btn-correct", "btn-incorrect", "btn-skip"):
+            self.query_one(f"#{btn_id}", Button).display = True
+
+        self._show_current_card()

studyctl/web/__init__.py

@@ -0,0 +1 @@
+"""Lightweight PWA web server for flashcard and quiz review."""

studyctl/web/app.py

@@ -0,0 +1,68 @@
+"""FastAPI application factory for the study PWA.
+
+Replaces the stdlib http.server with FastAPI + uvicorn.
+Serves JSON API endpoints and static PWA files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.base import BaseHTTPMiddleware
+
+if TYPE_CHECKING:
+    from starlette.responses import Response
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Add security headers to all responses."""
+
+    async def dispatch(self, request: Request, call_next) -> Response:  # type: ignore[override]
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        return response
+
+
+def create_app(study_dirs: list[str] | None = None) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        study_dirs: List of directory paths containing flashcard/quiz content.
+    """
+    app = FastAPI(
+        title="Socratic Study Mentor",
+        docs_url=None,
+        redoc_url=None,
+    )
+
+    # Store config on app state for route access
+    app.state.study_dirs = study_dirs or []
+
+    # Security headers
+    app.add_middleware(SecurityHeadersMiddleware)
+
+    # Register API routes
+    from studyctl.web.routes import artefacts, cards, courses, history
+
+    app.include_router(courses.router, prefix="/api")
+    app.include_router(cards.router, prefix="/api")
+    app.include_router(history.router, prefix="/api")
+    app.include_router(artefacts.router)
+
+    # Serve index.html at root
+    @app.get("/")
+    async def index() -> FileResponse:
+        return FileResponse(STATIC_DIR / "index.html")
+
+    # Mount static files LAST (catch-all)
+    app.mount("/", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+    return app

studyctl/web/routes/__init__.py

@@ -0,0 +1 @@
+"""FastAPI route modules."""

studyctl/web/routes/artefacts.py

@@ -0,0 +1,57 @@
+"""Artefact serving routes with path traversal protection."""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003 — used at runtime for resolve/is_relative_to
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from studyctl.settings import load_settings
+
+router = APIRouter()
+
+
+def _validate_artefact_path(course: str, artefact_type: str, filename: str) -> Path:
+    """Resolve and validate artefact path against directory traversal.
+
+    Ensures the resolved path is a child of content.base_path.
+    Raises 404 if path escapes the base or file doesn't exist.
+    """
+    base = load_settings().content.base_path
+    resolved = (base / course / artefact_type / filename).resolve()
+    if not resolved.is_relative_to(base.resolve()):
+        raise HTTPException(status_code=404)
+    if not resolved.is_file():
+        raise HTTPException(status_code=404)
+    return resolved
+
+
+@router.get("/artefacts/{course}/{artefact_type}/{filename:path}")
+def serve_artefact(course: str, artefact_type: str, filename: str) -> FileResponse:
+    """Serve an artefact file (audio, video, slides, etc.) with path validation."""
+    path = _validate_artefact_path(course, artefact_type, filename)
+    return FileResponse(path)
+
+
+@router.get("/api/artefacts/{course}")
+def list_artefacts(course: str) -> list[dict]:
+    """List all artefacts for a course grouped by type."""
+    base = load_settings().content.base_path
+    course_dir = base / course
+    if not course_dir.is_dir():
+        raise HTTPException(status_code=404, detail=f"Course '{course}' not found")
+
+    result = []
+    for type_dir in sorted(course_dir.iterdir()):
+        if not type_dir.is_dir() or type_dir.name.startswith("."):
+            continue
+        files = sorted(f.name for f in type_dir.iterdir() if f.is_file())
+        if files:
+            result.append(
+                {
+                    "type": type_dir.name,
+                    "files": files,
+                }
+            )
+    return result

studyctl/web/routes/cards.py

@@ -0,0 +1,86 @@
+"""Card API routes — load cards/quizzes, record reviews."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from studyctl.review_db import record_card_review
+from studyctl.review_loader import (
+    discover_directories,
+    find_content_dirs,
+    load_flashcards,
+    load_quizzes,
+)
+
+router = APIRouter()
+
+
+class ReviewRequest(BaseModel):
+    """POST /api/review request body."""
+
+    course: str
+    card_hash: str
+    correct: bool
+    card_type: str = "flashcard"
+    response_time_ms: int | None = None
+
+
+@router.get("/cards/{course}")
+def get_cards(request: Request, course: str, mode: str = "flashcards") -> list[dict]:
+    """Load flashcards or quiz questions for a course."""
+    courses = discover_directories(request.app.state.study_dirs)
+    match = next(((n, p) for n, p in courses if n == course), None)
+    if not match:
+        raise HTTPException(status_code=404, detail=f"Course '{course}' not found")
+
+    _, path = match
+    fc_dir, quiz_dir = find_content_dirs(path)
+
+    if mode == "flashcards" and fc_dir:
+        cards = load_flashcards(fc_dir)
+        return [
+            {
+                "type": "flashcard",
+                "front": c.front,
+                "back": c.back,
+                "hash": c.card_hash,
+                "source": c.source,
+            }
+            for c in cards
+        ]
+    if mode == "quiz" and quiz_dir:
+        questions = load_quizzes(quiz_dir)
+        return [
+            {
+                "type": "quiz",
+                "question": q.question,
+                "options": [
+                    {
+                        "text": o.text,
+                        "is_correct": o.is_correct,
+                        "rationale": o.rationale,
+                    }
+                    for o in q.options
+                ],
+                "hint": q.hint,
+                "hash": q.card_hash,
+                "source": q.source,
+            }
+            for q in questions
+        ]
+
+    raise HTTPException(status_code=404, detail=f"No {mode} content for {course}")
+
+
+@router.post("/review")
+def post_review(body: ReviewRequest) -> dict:
+    """Record a single card review result."""
+    record_card_review(
+        course=body.course,
+        card_type=body.card_type,
+        card_hash=body.card_hash,
+        correct=body.correct,
+        response_time_ms=body.response_time_ms,
+    )
+    return {"ok": True}