studyctl 2.0.0__py3-none-any.whl

studyctl/sync.py

@@ -0,0 +1,229 @@
+"""Sync engine — Obsidian → NotebookLM via notebooklm-py CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .pdf import md_to_pdf
+from .settings import MIN_FILE_SIZE, SKIP_FILENAMES, SKIP_PATTERNS, SYNCABLE_EXTENSIONS, Topic
+from .state import SyncState, file_hash
+
+
+def _should_skip(path: Path) -> bool:
+    """Filter out low-value files."""
+    # Skip by directory/file pattern
+    for part in path.parts:
+        if part in SKIP_PATTERNS or part.startswith("."):
+            return True
+    # Skip by filename
+    if path.name in SKIP_FILENAMES:
+        return True
+    # Skip tiny files (stubs, empty templates)
+    return path.stat().st_size < MIN_FILE_SIZE
+
+
+def find_sources(topic: Topic) -> list[Path]:
+    """Find all syncable files for a topic, filtered for quality."""
+    sources = []
+    for base in topic.obsidian_paths:
+        if not base.exists():
+            continue
+        for ext in SYNCABLE_EXTENSIONS:
+            for p in sorted(base.rglob(f"*{ext}")):
+                if not _should_skip(p):
+                    sources.append(p)
+    return sources
+
+
+def find_changed_sources(topic: Topic, state: SyncState) -> list[Path]:
+    """Find sources that are new or changed since last sync."""
+    return [p for p in find_sources(topic) if state.needs_sync(p)]
+
+
+def _run_nlm(args: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    """Run a notebooklm CLI command."""
+    return subprocess.run(["notebooklm", *args], capture_output=True, text=True, check=check)
+
+
+def ensure_notebook(topic: Topic, state: SyncState) -> str:
+    """Get or create the NotebookLM notebook for a topic. Returns notebook_id."""
+    # Use pre-mapped ID if available
+    if topic.notebook_id:
+        state.set_notebook_id(topic.name, topic.notebook_id, topic.display_name)
+        state.save()
+        return topic.notebook_id
+
+    # Check state for previously created notebook
+    ts = state.get_topic(topic.name)
+    if ts.notebook_id:
+        return ts.notebook_id
+
+    # Check if notebook already exists by title
+    result = _run_nlm(["list", "--json"])
+    try:
+        notebooks = json.loads(result.stdout).get("notebooks", [])
+    except json.JSONDecodeError:
+        import sys
+
+        print(f"[studyctl] Failed to parse notebook list: {result.stdout[:200]}", file=sys.stderr)
+        notebooks = []
+    for nb in notebooks:
+        if nb["title"] == topic.display_name:
+            state.set_notebook_id(topic.name, nb["id"], nb["title"])
+            state.save()
+            return nb["id"]
+
+    # Create new notebook
+    result = _run_nlm(["create", topic.display_name, "--json"])
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        import sys
+
+        print(
+            f"[studyctl] Failed to parse create response: {result.stdout[:200]}",
+            file=sys.stderr,
+        )
+        data = {}
+    notebook_id = data.get("id") or data.get("notebook", {}).get("id", "")
+    state.set_notebook_id(topic.name, notebook_id, topic.display_name)
+    state.save()
+    return notebook_id
+
+
+def sync_source(
+    path: Path,
+    notebook_id: str,
+    topic_name: str,
+    state: SyncState,
+    pdf_dir: Path | None = None,
+    unique_name: str | None = None,
+) -> str | None:
+    """Sync a single file to NotebookLM. Converts .md to PDF first. Returns source_id or None."""
+    upload_path = path
+    if path.suffix == ".md" and pdf_dir:
+        pdf = md_to_pdf(path, pdf_dir, unique_name)
+        if pdf:
+            upload_path = pdf
+
+    result = _run_nlm(
+        ["source", "add", str(upload_path), "--notebook", notebook_id, "--json"],
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return None
+
+    source_id = data.get("source_id") or data.get("source", {}).get("id", "")
+    if not source_id:
+        return None
+    rel_path = str(path.relative_to(Path.home()))
+    state.record_sync(topic_name, rel_path, file_hash(path), source_id, notebook_id)
+    state.save()
+    return source_id
+
+
+def sync_topic(topic: Topic, state: SyncState, dry_run: bool = False, as_pdf: bool = True) -> dict:
+    """Sync all changed sources for a topic. Returns summary."""
+    changed = find_changed_sources(topic, state)
+    total = len(find_sources(topic))
+    if not changed:
+        return {"topic": topic.name, "total": total, "changed": 0, "synced": 0, "failed": 0}
+
+    if dry_run:
+        return {
+            "topic": topic.name,
+            "total": total,
+            "changed": len(changed),
+            "synced": 0,
+            "failed": 0,
+            "dry_run": True,
+            "files": [str(p.name) for p in changed[:10]],
+        }
+
+    notebook_id = ensure_notebook(topic, state)
+    synced = failed = 0
+
+    # Build unique names for files with duplicate stems
+    name_map = _build_unique_names(changed)
+
+    with tempfile.TemporaryDirectory(prefix="studyctl-pdf-") as pdf_dir:
+        pdf_path = Path(pdf_dir) if as_pdf else None
+        for path in changed:
+            unique = name_map.get(str(path))
+            if sync_source(
+                path, notebook_id, topic.name, state, pdf_dir=pdf_path, unique_name=unique
+            ):
+                synced += 1
+            else:
+                failed += 1
+
+    return {
+        "topic": topic.name,
+        "total": total,
+        "changed": len(changed),
+        "synced": synced,
+        "failed": failed,
+    }
+
+
+def _build_unique_names(paths: list[Path]) -> dict[str, str]:
+    """For files with duplicate stems, prefix with parent dir name.
+
+    e.g. two 'introduction.md' files become:
+      'the-software-designer-mindset--introduction'
+      'pythonic-patterns--introduction'
+    """
+    from collections import Counter
+
+    stem_counts = Counter(p.stem for p in paths)
+    duplicated = {stem for stem, count in stem_counts.items() if count > 1}
+
+    name_map: dict[str, str] = {}
+    for p in paths:
+        if p.stem in duplicated:
+            # Walk up parents until we find a distinguishing name
+            # e.g. .../the-software-designer-mindset/study-notes/introduction.md
+            #   → "the-software-designer-mindset--introduction"
+            parts = p.parts
+            for i in range(len(parts) - 2, 0, -1):
+                candidate = parts[i]
+                if candidate != "study-notes" and candidate != "lessons":
+                    name_map[str(p)] = f"{candidate}--{p.stem}"
+                    break
+            else:
+                name_map[str(p)] = f"{p.parent.name}--{p.stem}"
+
+    return name_map
+
+
+def generate_audio(topic: Topic, state: SyncState, instructions: str = "") -> str | None:
+    """Generate an audio overview for a topic. Returns artifact_id or None."""
+    ts = state.get_topic(topic.name)
+    if not ts.notebook_id:
+        return None
+
+    args = ["generate", "audio", "--notebook", ts.notebook_id, "--json"]
+    if instructions:
+        args.insert(2, instructions)
+
+    result = _run_nlm(args, check=False)
+    if result.returncode != 0:
+        return None
+    try:
+        return json.loads(result.stdout).get("task_id")
+    except json.JSONDecodeError:
+        import sys
+
+        print(
+            f"[studyctl] Failed to parse audio response: {result.stdout[:200]}",
+            file=sys.stderr,
+        )
+        return None

studyctl/tui/__main__.py

@@ -0,0 +1,33 @@
+"""Entry point for ``python -m studyctl.tui`` and ``textual serve``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from studyctl.tui.app import StudyApp
+
+config_path = Path.home() / ".config" / "studyctl" / "config.yaml"
+study_dirs: list[str] = []
+theme = ""
+dyslexic = False
+
+if config_path.exists():
+    try:
+        data = yaml.safe_load(config_path.read_text()) or {}
+        study_dirs = data.get("review", {}).get("directories", [])
+        tui_cfg = data.get("tui", {})
+        theme = tui_cfg.get("theme", "")
+        dyslexic = tui_cfg.get("dyslexic_friendly", False)
+    except Exception:
+        pass
+
+app = StudyApp(
+    study_dirs=study_dirs,
+    theme_name=theme,
+    dyslexic_friendly=dyslexic,
+)
+
+if __name__ == "__main__":
+    app.run()

studyctl/tui/app.py

@@ -0,0 +1,395 @@
+"""Textual TUI application for studyctl study management.
+
+Launch via ``studyctl tui``.  Requires the ``tui`` extra::
+
+    pip install studyctl[tui]
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import ClassVar, NamedTuple
+
+try:
+    from textual.app import App, ComposeResult
+    from textual.containers import Vertical
+    from textual.screen import ModalScreen
+    from textual.widgets import (
+        DataTable,
+        Footer,
+        Header,
+        OptionList,
+        Static,
+        TabbedContent,
+        TabPane,
+    )
+    from textual.widgets.option_list import Option
+except ImportError as _exc:
+    raise ImportError(
+        "The TUI requires the 'textual' package. Install it with:\n  pip install studyctl[tui]"
+    ) from _exc
+
+from studyctl.cli import TOPIC_KEYWORDS
+from studyctl.history import (
+    get_study_session_stats,
+    list_concepts,
+    spaced_repetition_due,
+    struggle_topics,
+)
+from studyctl.review_loader import (
+    discover_directories,
+    find_content_dirs,
+    load_flashcards,
+    load_quizzes,
+    shuffle_items,
+)
+
+
+class CourseInfo(NamedTuple):
+    """Typed representation of a discovered course directory."""
+
+    name: str
+    path: Path
+
+
+def _load_session_state() -> dict:
+    """Load session state from the JSON file, returning defaults on failure."""
+    state_path = Path.home() / ".config" / "studyctl" / "session-state.json"
+    try:
+        return json.loads(state_path.read_text()) if state_path.exists() else {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+class CoursePickerScreen(ModalScreen[CourseInfo | None]):
+    """Modal overlay for selecting a course directory."""
+
+    BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
+        ("escape", "cancel", "Cancel"),
+    ]
+
+    CSS = """
+    CoursePickerScreen {
+        align: center middle;
+    }
+    #course-picker-box {
+        width: 60;
+        max-height: 24;
+        border: round $accent;
+        background: $surface;
+        padding: 1 2;
+    }
+    #course-picker-title {
+        text-style: bold;
+        text-align: center;
+        margin-bottom: 1;
+    }
+    #course-picker {
+        max-height: 18;
+    }
+    """
+
+    def __init__(self, courses: list[CourseInfo]) -> None:
+        super().__init__()
+        self._courses = courses
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="course-picker-box"):
+            yield Static("Select a course", id="course-picker-title")
+            yield OptionList(
+                *[Option(course.name) for course in self._courses],
+                id="course-picker",
+            )
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        self.dismiss(self._courses[event.option_index])
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)
+
+
+class StudyApp(App):
+    """Read-only study management dashboard."""
+
+    TITLE = "studyctl"
+    CSS = """
+    Screen {
+        background: $surface;
+    }
+    #dashboard-content {
+        padding: 1 2;
+    }
+    .section-header {
+        text-style: bold;
+        color: $accent;
+        margin-bottom: 1;
+    }
+    .info-line {
+        margin-bottom: 0;
+    }
+
+    /* Dyslexic-friendly: wider spacing, more padding, clearer separation */
+    .dyslexic #dashboard-content {
+        padding: 2 4;
+    }
+    .dyslexic .section-header {
+        margin-bottom: 2;
+    }
+    .dyslexic .info-line {
+        margin-bottom: 1;
+    }
+    .dyslexic DataTable {
+        padding: 1 2;
+    }
+    .dyslexic #card-panel {
+        padding: 2 4;
+        min-height: 8;
+        margin: 2 1;
+    }
+    .dyslexic #progress-label {
+        margin: 2 0;
+    }
+    .dyslexic #status-label {
+        margin-bottom: 1;
+    }
+    .dyslexic .score-btn {
+        margin: 0 2;
+    }
+    """
+
+    BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
+        ("q", "quit", "Quit"),
+        ("d", "show_tab('dashboard')", "Dashboard"),
+        ("r", "show_tab('review')", "Review"),
+        ("c", "show_tab('concepts')", "Concepts"),
+        ("s", "show_tab('sessions')", "Sessions"),
+        ("f", "start_flashcards", "Flashcards"),
+        ("z", "start_quiz", "Quiz"),
+        ("o", "toggle_dyslexic", "OpenDyslexic"),
+    ]
+
+    def __init__(
+        self,
+        study_dirs: list[str] | None = None,
+        theme_name: str = "",
+        dyslexic_friendly: bool = False,
+        **kwargs: object,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._study_dirs = study_dirs or []
+        self._theme_name = theme_name
+        self._dyslexic_friendly = dyslexic_friendly
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with TabbedContent(
+            "Dashboard",
+            "Review",
+            "Concepts",
+            "Sessions",
+            "StudyCards",
+            id="tabs",
+        ):
+            with TabPane("Dashboard", id="dashboard"):
+                yield Vertical(
+                    Static("", id="dashboard-content"),
+                    id="dashboard-container",
+                )
+            with TabPane("Review", id="review"):
+                yield DataTable(id="review-table")
+            with TabPane("Concepts", id="concepts"):
+                yield DataTable(id="concepts-table")
+            with TabPane("Sessions", id="sessions"):
+                yield DataTable(id="sessions-table")
+            with TabPane("StudyCards", id="studycards"):
+                yield Vertical(
+                    Static("", id="studycards-content"),
+                    id="studycards-container",
+                )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        if self._theme_name:
+            self.theme = self._theme_name
+        if self._dyslexic_friendly:
+            self.add_class("dyslexic")
+            self.notify(
+                "Dyslexic-friendly mode ON. For best results, set your "
+                "terminal font to OpenDyslexic: https://opendyslexic.org",
+                title="Accessibility",
+                timeout=8,
+            )
+        self._populate_dashboard()
+        self._populate_review()
+        self._populate_concepts()
+        self._populate_sessions()
+        self._populate_studycards()
+
+    def action_show_tab(self, tab_id: str) -> None:
+        tabs = self.query_one(TabbedContent)
+        tabs.active = tab_id
+
+    def action_toggle_dyslexic(self) -> None:
+        """Toggle dyslexic-friendly mode (wider spacing)."""
+        self.toggle_class("dyslexic")
+        if self.has_class("dyslexic"):
+            self.notify(
+                "Dyslexic-friendly mode ON — wider spacing applied. "
+                "Set terminal font to OpenDyslexic for best results.",
+                title="Accessibility",
+            )
+        else:
+            self.notify("Dyslexic-friendly mode OFF")
+
+    # ------------------------------------------------------------------
+    # Tab population
+    # ------------------------------------------------------------------
+
+    def _populate_dashboard(self) -> None:
+        state = _load_session_state()
+        energy = state.get("energy", "unknown")
+        topic = state.get("topic", "none")
+
+        due = spaced_repetition_due(TOPIC_KEYWORDS)
+        struggles = struggle_topics()
+
+        lines = [
+            "[bold]Study Dashboard[/bold]",
+            "",
+            f"  Energy level:   {energy}",
+            f"  Current topic:  {topic}",
+            f"  Reviews due:    {len(due)}",
+            f"  Struggle areas: {len(struggles)}",
+        ]
+        if struggles:
+            lines.append("")
+            lines.append("[bold]Top struggles:[/bold]")
+            for s in struggles[:5]:
+                lines.append(f"  • {s['topic']} ({s['mentions']} mentions)")
+
+        widget = self.query_one("#dashboard-content", Static)
+        widget.update("\n".join(lines))
+
+    def _populate_review(self) -> None:
+        table = self.query_one("#review-table", DataTable)
+        table.add_columns("Topic", "Last Studied", "Days Ago", "Review Type")
+
+        for item in spaced_repetition_due(TOPIC_KEYWORDS):
+            table.add_row(
+                item["topic"],
+                item.get("last_studied") or "never",
+                str(item.get("days_ago") or "—"),
+                item.get("review_type", ""),
+            )
+
+    def _populate_concepts(self) -> None:
+        table = self.query_one("#concepts-table", DataTable)
+        table.add_columns("Name", "Domain", "Description")
+
+        for concept in list_concepts():
+            table.add_row(concept.name, concept.domain, concept.description or "")
+
+    def _populate_sessions(self) -> None:
+        table = self.query_one("#sessions-table", DataTable)
+        table.add_columns("Topic", "Sessions", "Total Min", "Avg Min")
+
+        for stat in get_study_session_stats():
+            table.add_row(
+                stat.get("topic") or "unknown",
+                str(stat.get("sessions", 0)),
+                str(round(stat.get("total_minutes") or 0)),
+                str(round(stat.get("avg_minutes") or 0)),
+            )
+
+    def _discover_courses(self) -> list[CourseInfo]:
+        """Discover courses and wrap raw tuples as CourseInfo."""
+        return [CourseInfo(*t) for t in discover_directories(self._study_dirs)]
+
+    def _populate_studycards(self) -> None:
+        content = self.query_one("#studycards-content", Static)
+        courses = self._discover_courses()
+
+        if not courses:
+            content.update(
+                "[bold]Study Cards[/bold]\n\n"
+                "  No courses found.\n\n"
+                "  Configure directories in ~/.config/studyctl/config.yaml:\n"
+                "    review:\n"
+                "      directories:\n"
+                "        - ~/Desktop/ZTM-DE/downloads\n"
+                "        - ~/Desktop/Python/downloads\n\n"
+                "  Or press [bold]f[/bold] for flashcards / [bold]z[/bold] for quiz"
+                " and select a directory."
+            )
+            return
+
+        lines = [
+            "[bold]Study Cards[/bold]\n",
+            f"  Found {len(courses)} course(s):\n",
+        ]
+        for course in courses:
+            fc_dir, quiz_dir = find_content_dirs(course.path)
+            fc_count = len(load_flashcards(fc_dir)) if fc_dir else 0
+            quiz_count = len(load_quizzes(quiz_dir)) if quiz_dir else 0
+            lines.append(
+                f"  • [bold]{course.name}[/bold] — {fc_count} flashcards,"
+                f" {quiz_count} quiz questions"
+            )
+
+        lines.append("\n  Press [bold]f[/bold] for flashcards / [bold]z[/bold] for quiz")
+        content.update("\n".join(lines))
+
+    def _launch_study(self, mode: str = "flashcards") -> None:
+        """Launch interactive study session."""
+        courses = self._discover_courses()
+        if not courses:
+            self.notify(
+                "No courses found. Configure review.directories in config.yaml",
+                severity="error",
+            )
+            return
+
+        if len(courses) == 1:
+            self._start_session(courses[0], mode)
+        else:
+            self.push_screen(
+                CoursePickerScreen(courses),
+                lambda result: self._start_session(result, mode) if result else None,
+            )
+
+    def _start_session(self, course: CourseInfo, mode: str) -> None:
+        """Start a study session for the selected course."""
+        fc_dir, quiz_dir = find_content_dirs(course.path)
+
+        if mode == "flashcards" and fc_dir:
+            cards = shuffle_items(load_flashcards(fc_dir))
+        elif mode == "quiz" and quiz_dir:
+            cards = shuffle_items(load_quizzes(quiz_dir))
+        else:
+            self.notify(
+                f"No {mode} content found for {course.name}",
+                severity="warning",
+            )
+            return
+
+        if not cards:
+            self.notify(f"No {mode} cards loaded", severity="warning")
+            return
+
+        from studyctl.tui.study_cards import StudyCardsTab
+
+        # Replace studycards content with the interactive widget
+        container = self.query_one("#studycards-container", Vertical)
+        container.remove_children()
+        container.mount(StudyCardsTab(cards=cards, course_name=course.name, mode=mode))
+
+        # Switch to the tab
+        tabs = self.query_one(TabbedContent)
+        tabs.active = "studycards"
+
+    def action_start_flashcards(self) -> None:
+        self._launch_study("flashcards")
+
+    def action_start_quiz(self) -> None:
+        self._launch_study("quiz")