studyctl 2.0.0__py3-none-any.whl

studyctl/__init__.py

@@ -0,0 +1,3 @@
+"""studyctl — AuDHD study pipeline CLI."""
+
+__version__ = "1.0.0"

studyctl/calendar.py

@@ -0,0 +1,140 @@
+"""Calendar time-blocking via ICS file generation."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from uuid import uuid4
+
+# Spaced repetition review types with suggested durations (minutes)
+REVIEW_DURATIONS: dict[str, int] = {
+    "5-min recall quiz": 10,
+    "10-min Socratic review": 15,
+    "15-min deep review": 20,
+    "Apply to new problem": 30,
+    "Teach-back session": 30,
+}
+
+
+def _ics_dt(dt: datetime) -> str:
+    """Format datetime as ICS DTSTART/DTEND value with UTC suffix."""
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(UTC)
+        return dt.strftime("%Y%m%dT%H%M%SZ")
+    return dt.strftime("%Y%m%dT%H%M%S")
+
+
+def _escape(text: str) -> str:
+    """Escape text for ICS fields."""
+    return text.replace("\\", "\\\\").replace(",", "\\,").replace(";", "\\;").replace("\n", "\\n")
+
+
+def generate_event(
+    topic: str,
+    review_type: str,
+    start: datetime,
+    duration_min: int | None = None,
+) -> str:
+    """Generate a single VEVENT block."""
+    dur = duration_min or REVIEW_DURATIONS.get(review_type, 20)
+    end = start + timedelta(minutes=dur)
+    uid = f"{uuid4()}@studyctl"
+    now = datetime.now(UTC)
+
+    return (
+        "BEGIN:VEVENT\r\n"
+        f"UID:{uid}\r\n"
+        f"DTSTAMP:{_ics_dt(now)}\r\n"
+        f"DTSTART:{_ics_dt(start)}\r\n"
+        f"DTEND:{_ics_dt(end)}\r\n"
+        f"SUMMARY:{_escape(f'Study: {topic} ({review_type})')}\r\n"
+        f"DESCRIPTION:{_escape(f'Spaced repetition: {review_type} for {topic}')}\r\n"
+        "STATUS:CONFIRMED\r\n"
+        "BEGIN:VALARM\r\n"
+        "TRIGGER:-PT5M\r\n"
+        "ACTION:DISPLAY\r\n"
+        f"DESCRIPTION:{_escape(f'Study time: {topic}')}\r\n"
+        "END:VALARM\r\n"
+        "END:VEVENT\r\n"
+    )
+
+
+def generate_ics(events: list[dict]) -> str:
+    """Generate a complete .ics file from a list of event dicts.
+
+    Each dict: {topic, review_type, start, duration_min?}
+    """
+    lines = (
+        "BEGIN:VCALENDAR\r\n"
+        "VERSION:2.0\r\n"
+        "PRODID:-//studyctl//Socratic Study Mentor//EN\r\n"
+        "CALSCALE:GREGORIAN\r\n"
+        "METHOD:PUBLISH\r\n"
+    )
+    for evt in events:
+        lines += generate_event(
+            topic=evt["topic"],
+            review_type=evt["review_type"],
+            start=evt["start"],
+            duration_min=evt.get("duration_min"),
+        )
+    lines += "END:VCALENDAR\r\n"
+    return lines
+
+
+def schedule_reviews(
+    due_items: list[dict],
+    start_time: datetime | None = None,
+    gap_minutes: int = 10,
+) -> list[dict]:
+    """Convert spaced repetition due items into scheduled events.
+
+    Args:
+        due_items: From history.spaced_repetition_due() — [{topic, review_type, ...}]
+        start_time: When to start scheduling (default: next hour)
+        gap_minutes: Gap between sessions
+
+    Returns:
+        List of event dicts ready for generate_ics()
+    """
+    if not start_time:
+        now = datetime.now()
+        start_time = now.replace(minute=0, second=0, microsecond=0) + timedelta(hours=1)
+
+    events = []
+    current = start_time
+    for item in due_items:
+        review_type = item.get("review_type", "15-min deep review")
+        duration = REVIEW_DURATIONS.get(review_type, 20)
+        events.append(
+            {
+                "topic": item["topic"],
+                "review_type": review_type,
+                "start": current,
+                "duration_min": duration,
+            }
+        )
+        current += timedelta(minutes=duration + gap_minutes)
+    return events
+
+
+def write_ics(
+    events: list[dict],
+    output_dir: Path | None = None,
+) -> Path:
+    """Write events to an .ics file.
+
+    Args:
+        events: Event dicts from schedule_reviews()
+        output_dir: Directory to write to (default: ~/Downloads)
+
+    Returns:
+        Path to the written .ics file
+    """
+    output_dir = output_dir or Path.home() / "Downloads"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M")
+    path = output_dir / f"study-blocks-{timestamp}.ics"
+    path.write_text(generate_ics(events))
+    return path

studyctl/cli/__init__.py

@@ -0,0 +1,56 @@
+"""studyctl CLI — sync, plan, and schedule study sessions.
+
+Split into submodules with LazyGroup for fast startup.
+Commands are only imported when invoked.
+"""
+
+from __future__ import annotations
+
+import click
+
+from studyctl.cli._lazy import LazyGroup
+
+
+@click.group(
+    cls=LazyGroup,
+    lazy_subcommands={
+        # _sync.py — Obsidian/NotebookLM sync
+        "sync": "studyctl.cli._sync:sync",
+        "status": "studyctl.cli._sync:status",
+        "audio": "studyctl.cli._sync:audio",
+        "topics": "studyctl.cli._sync:topics",
+        "dedup": "studyctl.cli._sync:dedup",
+        # _state.py — cross-machine state
+        "state": "studyctl.cli._state:state_group",
+        # _setup.py — first-run setup wizard
+        "setup": "studyctl.cli._setup:setup",
+        # _config.py — configuration
+        "config": "studyctl.cli._config:config_group",
+        # _schedule.py — job scheduling + calendar
+        "schedule": "studyctl.cli._schedule:schedule_group",
+        "schedule-blocks": "studyctl.cli._schedule:schedule_blocks",
+        # _review.py — spaced repetition, progress, teachback, bridges
+        "review": "studyctl.cli._review:review",
+        "struggles": "studyctl.cli._review:struggles",
+        "wins": "studyctl.cli._review:wins",
+        "progress": "studyctl.cli._review:progress",
+        "resume": "studyctl.cli._review:resume",
+        "streaks": "studyctl.cli._review:streaks",
+        "progress-map": "studyctl.cli._review:progress_map",
+        "teachback": "studyctl.cli._review:teachback",
+        "teachback-history": "studyctl.cli._review:teachback_history_cmd",
+        "bridge": "studyctl.cli._review:bridge_group",
+        # _content.py — content pipeline (pdf splitting, NotebookLM, syllabus)
+        "content": "studyctl.cli._content:content_group",
+        # _web.py — web UI, TUI, docs
+        "web": "studyctl.cli._web:web",
+        "tui": "studyctl.cli._web:tui",
+        "docs": "studyctl.cli._web:docs_group",
+    },
+)
+@click.version_option()
+def cli() -> None:
+    """studyctl — AuDHD study pipeline: Obsidian\u2192NotebookLM sync and study management."""
+
+
+__all__ = ["cli"]

studyctl/cli/_config.py

@@ -0,0 +1,128 @@
+"""Config commands — configuration management."""
+
+from __future__ import annotations
+
+import click
+from rich.table import Table
+
+from studyctl.cli._shared import console, offer_agent_install
+from studyctl.shared import init_interactive_config
+
+
+@click.group(name="config")
+def config_group() -> None:
+    """Manage studyctl configuration."""
+
+
+@config_group.command(name="init")
+@click.option(
+    "--install-agents/--no-install-agents",
+    default=None,
+    help="Install AI agent definitions after config (auto-detects available tools).",
+)
+def config_init(install_agents: bool | None) -> None:
+    """Interactive setup — configure knowledge bridging, NotebookLM, and Obsidian integration."""
+    path = init_interactive_config(console)
+    console.print(f"\n[bold green]\u2713 Configuration saved to {path}[/bold green]")
+
+    # Offer to install agents
+    offer_agent_install(install_agents)
+
+    console.print("\nNext steps:")
+    console.print("  1. Add study topics:  studyctl topics")
+    console.print("  2. Start a session:   /agent socratic-mentor  (Claude Code)")
+    console.print("                        kiro-cli chat --agent study-mentor  (Kiro)")
+
+
+@config_group.command(name="show")
+def config_show() -> None:
+    """Display current configuration."""
+    from studyctl.settings import _CONFIG_PATH, load_settings
+
+    settings = load_settings()
+    config_path = _CONFIG_PATH
+
+    if not config_path.exists():
+        console.print("[red]No config file found.[/red] Run: studyctl config init")
+        return
+
+    console.print(f"[bold]Configuration[/bold] \u2014 {config_path}\n")
+
+    # Core settings
+    table = Table(title="Core Settings")
+    table.add_column("Setting", style="cyan")
+    table.add_column("Value")
+    table.add_column("Status", justify="center")
+
+    # Obsidian
+    obsidian_path = settings.obsidian_base
+    obsidian_exists = obsidian_path.exists()
+    table.add_row(
+        "Obsidian vault",
+        str(obsidian_path),
+        "[green]\u2713[/green]" if obsidian_exists else "[red]\u2717[/red]",
+    )
+
+    # Session DB
+    db_exists = settings.session_db.exists()
+    table.add_row(
+        "Session database",
+        str(settings.session_db),
+        "[green]\u2713[/green]" if db_exists else "[dim]\u2014[/dim]",
+    )
+
+    # State dir
+    state_exists = settings.state_dir.exists()
+    table.add_row(
+        "State directory",
+        str(settings.state_dir),
+        "[green]\u2713[/green]" if state_exists else "[dim]\u2014[/dim]",
+    )
+
+    # Knowledge domains
+    kd = settings.knowledge_domains
+    if kd.primary:
+        table.add_row("Knowledge bridging", f"Primary: {kd.primary}", "[green]\u2713[/green]")
+    else:
+        table.add_row("Knowledge bridging", "Not configured", "[dim]\u2014[/dim]")
+
+    # NotebookLM
+    nlm_enabled = settings.notebooklm.enabled
+    table.add_row(
+        "NotebookLM",
+        "Enabled" if nlm_enabled else "Disabled",
+        "[green]\u2713[/green]" if nlm_enabled else "[dim]\u2014[/dim]",
+    )
+
+    # Sync
+    if settings.sync_remote:
+        table.add_row("Sync remote", settings.sync_remote, "[green]\u2713[/green]")
+    else:
+        table.add_row("Sync remote", "Not configured", "[dim]\u2014[/dim]")
+
+    console.print(table)
+
+    # Topics
+    if settings.topics:
+        topics_table = Table(title="\nStudy Topics")
+        topics_table.add_column("Name", style="bold")
+        topics_table.add_column("Slug", style="dim")
+        topics_table.add_column("Path")
+        topics_table.add_column("Notebook", style="dim")
+        topics_table.add_column("Tags")
+
+        for t in settings.topics:
+            path_str = str(t.obsidian_path)
+            path_str = (
+                f"[green]{path_str}[/green]"
+                if t.obsidian_path.exists()
+                else f"[red]{path_str}[/red]"
+            )
+
+            nb = t.notebook_id[:12] + "\u2026" if t.notebook_id else "[dim]\u2014[/dim]"
+            tags = ", ".join(t.tags) if t.tags else "[dim]\u2014[/dim]"
+            topics_table.add_row(t.name, t.slug, path_str, nb, tags)
+
+        console.print(topics_table)
+    else:
+        console.print("\n[dim]No topics configured. Add topics to config.yaml.[/dim]")