studyctl 2.0.0__py3-none-any.whl

studyctl/maintenance.py

@@ -0,0 +1,69 @@
+"""NotebookLM notebook maintenance — dedup, cleanup."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections import defaultdict
+
+
+def _run_nlm(args: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(["notebooklm", *args], capture_output=True, text=True, check=check)
+
+
+def find_duplicates(notebook_id: str) -> dict[str, list[dict]]:
+    """Find duplicate sources by title in a notebook. Returns {title: [sources]}."""
+    result = _run_nlm(["source", "list", "--notebook", notebook_id, "--json"])
+    try:
+        sources = json.loads(result.stdout).get("sources", [])
+    except json.JSONDecodeError:
+        import sys
+
+        print(f"[studyctl] Failed to parse source list: {result.stdout[:200]}", file=sys.stderr)
+        return {}
+
+    by_title: dict[str, list[dict]] = defaultdict(list)
+    for s in sources:
+        by_title[s["title"]].append(s)
+
+    return {t: srcs for t, srcs in by_title.items() if len(srcs) > 1}
+
+
+def dedup_notebook(notebook_id: str, dry_run: bool = False) -> dict:
+    """Remove TRUE duplicates (same title, same source origin).
+
+    For legitimate duplicates (same filename from different dirs),
+    we keep all of them — the sync engine should have given them
+    unique names. This only removes exact duplicates from re-syncing.
+
+    Strategy: group by title. If >2 copies, keep 2 (could be legit
+    from different dirs). If all have identical source metadata,
+    keep only 1.
+    """
+    result = _run_nlm(["source", "list", "--notebook", notebook_id, "--json"])
+    try:
+        sources = json.loads(result.stdout).get("sources", [])
+    except json.JSONDecodeError:
+        import sys
+
+        print(f"[studyctl] Failed to parse source list: {result.stdout[:200]}", file=sys.stderr)
+        return {"duplicates": 0, "removed": 0, "titles": []}
+
+    by_title: dict[str, list[dict]] = defaultdict(list)
+    for s in sources:
+        by_title[s["title"]].append(s)
+
+    removed = 0
+    titles = []
+    for title, srcs in by_title.items():
+        if len(srcs) <= 1:
+            continue
+        # Keep the last one, delete earlier duplicates
+        to_delete = srcs[:-1]
+        for s in to_delete:
+            if not dry_run:
+                _run_nlm(["source", "delete", s["id"], "-n", notebook_id, "-y"], check=False)
+            removed += 1
+        titles.append(title)
+
+    return {"duplicates": removed, "removed": removed, "titles": titles}

studyctl/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server for studyctl — exposes study tools to AI coding assistants."""

studyctl/mcp/server.py

@@ -0,0 +1,58 @@
+"""FastMCP v1 server for studyctl.
+
+Provides study tools to AI coding assistants via stdio transport.
+Register with: ``claude mcp add studyctl-mcp``
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import FastMCP
+
+from studyctl.settings import Settings, get_db_path, load_settings
+
+
+@dataclass
+class AppState:
+    """Shared state available to all tools via server context."""
+
+    db: sqlite3.Connection
+    settings: Settings
+
+
+@asynccontextmanager
+async def lifespan(server: FastMCP):
+    """Initialize shared DB connection and settings for tool lifetime."""
+    db_path = get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    db = sqlite3.connect(db_path)
+    db.execute("PRAGMA journal_mode=WAL")
+    db.execute("PRAGMA busy_timeout=5000")
+
+    from studyctl.review_db import ensure_tables
+
+    ensure_tables(db_path)
+
+    settings = load_settings()
+    yield AppState(db=db, settings=settings)
+    db.close()
+
+
+mcp = FastMCP("studyctl", lifespan=lifespan)
+
+# Register tools from tools module
+from studyctl.mcp.tools import register_tools  # noqa: E402
+
+register_tools(mcp)
+
+
+def main() -> None:
+    """Entry point for studyctl-mcp command."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

studyctl/mcp/tools.py

@@ -0,0 +1,234 @@
+"""MCP tool implementations for studyctl.
+
+Each tool is registered via ``register_tools(mcp)`` and uses the
+lifespan AppState for shared DB/settings access.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP  # noqa: TC002 — used at runtime as param type
+from mcp.server.fastmcp.exceptions import ToolError
+
+from studyctl.review_db import (
+    get_course_stats,
+    get_due_cards,
+    record_card_review,
+)
+from studyctl.review_loader import (
+    discover_directories,
+    find_content_dirs,
+    load_flashcards,
+    load_quizzes,
+)
+from studyctl.settings import load_settings
+
+logger = logging.getLogger(__name__)
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register all studyctl MCP tools on the server."""
+
+    @mcp.tool()
+    def list_courses() -> dict[str, Any]:
+        """List all available study courses with card counts and review stats.
+
+        Returns courses discovered from the review.directories config.
+        Each course has: name, card_count, quiz_count, due_count.
+        """
+        raw_config = {}
+        config_path = Path.home() / ".config" / "studyctl" / "config.yaml"
+        if config_path.exists():
+            import yaml
+
+            raw_config = yaml.safe_load(config_path.read_text()) or {}
+        study_dirs = raw_config.get("review", {}).get("directories", [])
+
+        courses = discover_directories(study_dirs)
+        result = []
+        for name, path in courses:
+            fc_dir, quiz_dir = find_content_dirs(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
+            due = len(get_due_cards(name))
+            result.append(
+                {
+                    "name": name,
+                    "card_count": fc_count,
+                    "quiz_count": quiz_count,
+                    "due_count": due,
+                }
+            )
+        return {"courses": result}
+
+    @mcp.tool()
+    def get_study_context(course: str) -> dict[str, Any]:
+        """Get current study state for a course — due cards, stats, weak areas.
+
+        Use this to understand where the student is before starting a session.
+
+        Args:
+            course: Course name (as returned by list_courses).
+        """
+        stats = get_course_stats(course)
+        due = get_due_cards(course)
+        return {
+            "due_cards": len(due),
+            "total_reviews": stats.get("total_reviews", 0),
+            "unique_cards": stats.get("unique_cards", 0),
+            "mastered": stats.get("mastered", 0),
+            "due_today": stats.get("due_today", 0),
+        }
+
+    @mcp.tool()
+    def record_study_progress(course: str, card_hash: str, correct: bool) -> dict[str, str]:
+        """Record a review result for a single card.
+
+        Args:
+            course: Course name.
+            card_hash: The card's hash identifier.
+            correct: Whether the student answered correctly.
+        """
+        record_card_review(
+            course=course,
+            card_type="flashcard",
+            card_hash=card_hash,
+            correct=correct,
+        )
+        return {"status": "recorded"}
+
+    @mcp.tool()
+    def generate_flashcards(course: str, chapter: int, content: str) -> dict[str, Any]:
+        """Save agent-generated flashcards to a course directory.
+
+        The content parameter should be a JSON string with the flashcard data:
+        {"title": "Chapter N", "cards": [{"front": "...", "back": "..."}, ...]}
+
+        Validates the JSON structure before writing.
+
+        Args:
+            course: Course slug (directory name under content.base_path).
+            chapter: Chapter number (used in filename).
+            content: JSON string with flashcard data.
+        """
+        try:
+            data = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise ToolError(f"Invalid JSON: {exc}") from exc
+
+        # Validate structure
+        if not isinstance(data, dict) or "cards" not in data:
+            raise ToolError("JSON must have a 'cards' array")
+        if not isinstance(data["cards"], list):
+            raise ToolError("'cards' must be a list")
+        for i, card in enumerate(data["cards"]):
+            if not isinstance(card, dict):
+                raise ToolError(f"Card {i} must be an object")
+            if "front" not in card or "back" not in card:
+                raise ToolError(f"Card {i} missing 'front' or 'back'")
+
+        settings = load_settings()
+        base = settings.content.base_path
+        course_dir = base / course / "flashcards"
+        course_dir.mkdir(parents=True, exist_ok=True)
+
+        filename = f"ch{chapter:02d}-flashcards.json"
+        path = course_dir / filename
+        path.write_text(json.dumps(data, indent=2))
+        logger.info("Wrote %d flashcards to %s", len(data["cards"]), path)
+        return {"path": str(path), "count": len(data["cards"])}
+
+    @mcp.tool()
+    def generate_quiz(course: str, chapter: int, content: str) -> dict[str, Any]:
+        """Save agent-generated quiz questions to a course directory.
+
+        The content parameter should be a JSON string with quiz data:
+        {"title": "Chapter N Quiz", "questions": [{"question": "...",
+        "answerOptions": [{"text": "...", "isCorrect": true}, ...]}]}
+
+        Validates the JSON structure before writing.
+
+        Args:
+            course: Course slug (directory name under content.base_path).
+            chapter: Chapter number (used in filename).
+            content: JSON string with quiz data.
+        """
+        try:
+            data = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise ToolError(f"Invalid JSON: {exc}") from exc
+
+        if not isinstance(data, dict) or "questions" not in data:
+            raise ToolError("JSON must have a 'questions' array")
+        if not isinstance(data["questions"], list):
+            raise ToolError("'questions' must be a list")
+        for i, q in enumerate(data["questions"]):
+            if not isinstance(q, dict):
+                raise ToolError(f"Question {i} must be an object")
+            if "question" not in q:
+                raise ToolError(f"Question {i} missing 'question' field")
+            if "answerOptions" not in q:
+                raise ToolError(f"Question {i} missing 'answerOptions'")
+
+        settings = load_settings()
+        base = settings.content.base_path
+        course_dir = base / course / "quizzes"
+        course_dir.mkdir(parents=True, exist_ok=True)
+
+        filename = f"ch{chapter:02d}-quiz.json"
+        path = course_dir / filename
+        path.write_text(json.dumps(data, indent=2))
+        logger.info("Wrote %d questions to %s", len(data["questions"]), path)
+        return {"path": str(path), "count": len(data["questions"])}
+
+    @mcp.tool()
+    def get_chapter_text(course: str, chapter: int) -> dict[str, str]:
+        """Extract text from a chapter PDF for LLM processing.
+
+        Requires pymupdf. Returns the chapter title and full text content.
+
+        Args:
+            course: Course slug.
+            chapter: Chapter number (1-indexed).
+        """
+        try:
+            import pymupdf
+        except ImportError:
+            raise ToolError(
+                "pymupdf not installed. Install with: uv pip install 'studyctl[content]'"
+            ) from None
+
+        settings = load_settings()
+        chapters_dir = settings.content.base_path / course / "chapters"
+        if not chapters_dir.is_dir():
+            raise ToolError(
+                f"No chapters directory for course '{course}'. Run 'studyctl content split' first."
+            )
+
+        # Find chapter PDF by number prefix
+        pattern = f"*ch{chapter:02d}*" if chapter < 100 else f"*{chapter}*"
+        matches = sorted(chapters_dir.glob(f"{pattern}.pdf"))
+        if not matches:
+            # Try broader match
+            all_pdfs = sorted(chapters_dir.glob("*.pdf"))
+            if chapter <= len(all_pdfs):
+                matches = [all_pdfs[chapter - 1]]
+            else:
+                raise ToolError(
+                    f"Chapter {chapter} not found in {chapters_dir}. "
+                    f"Available: {len(all_pdfs)} PDFs."
+                )
+
+        pdf_path = matches[0]
+        doc = pymupdf.open(str(pdf_path))
+        text = ""
+        for page in doc:
+            text += page.get_text()
+        doc.close()
+
+        title = pdf_path.stem.replace("_", " ").replace("-", " ").title()
+        return {"title": title, "text": text}

studyctl/pdf.py

@@ -0,0 +1,89 @@
+"""Markdown → PDF conversion with mermaid diagram rendering."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+MERMAID_BLOCK = re.compile(r"```mermaid\s*\n(.*?)```", re.DOTALL)
+
+
+def _render_mermaid(code: str, output_path: Path) -> bool:
+    """Render a mermaid code block to PNG."""
+    with tempfile.NamedTemporaryFile(suffix=".mmd", mode="w", delete=False) as f:
+        f.write(code)
+        mmd_path = f.name
+    result = subprocess.run(
+        [
+            "npx",
+            "-y",
+            "@mermaid-js/mermaid-cli",
+            "-i",
+            mmd_path,
+            "-o",
+            str(output_path),
+            "-b",
+            "white",
+            "-q",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    Path(mmd_path).unlink(missing_ok=True)
+    return result.returncode == 0 and output_path.exists()
+
+
+def _preprocess_mermaid(md_content: str, work_dir: Path) -> str:
+    """Replace mermaid code blocks with rendered PNG image references."""
+    counter = 0
+
+    def replace_block(match: re.Match) -> str:
+        nonlocal counter
+        counter += 1
+        code = match.group(1).strip()
+        png_path = work_dir / f"mermaid_{counter}.png"
+        if _render_mermaid(code, png_path):
+            return f"![diagram]({png_path})"
+        # Fallback: keep as code block if rendering fails
+        return match.group(0)
+
+    return MERMAID_BLOCK.sub(replace_block, md_content)
+
+
+def md_to_pdf(md_path: Path, pdf_dir: Path, unique_name: str | None = None) -> Path | None:
+    """Convert markdown to PDF, rendering mermaid diagrams as images."""
+    stem = unique_name or md_path.stem
+    pdf_path = pdf_dir / (stem + ".pdf")
+    content = md_path.read_text()
+
+    has_mermaid = "```mermaid" in content
+
+    with tempfile.TemporaryDirectory(prefix="studyctl-mermaid-") as mermaid_dir:
+        if has_mermaid:
+            processed = _preprocess_mermaid(content, Path(mermaid_dir))
+            # Write processed markdown to temp file
+            tmp_md = Path(mermaid_dir) / md_path.name
+            tmp_md.write_text(processed)
+            source = tmp_md
+        else:
+            source = md_path
+
+        result = subprocess.run(
+            [
+                "pandoc",
+                str(source),
+                "-o",
+                str(pdf_path),
+                "--pdf-engine=xelatex",
+                "-V",
+                "geometry:margin=1in",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+    if result.returncode == 0 and pdf_path.exists():
+        return pdf_path
+    return None