learnx-cli 0.3.0__py3-none-any.whl

tutor/cli/shell.py

@@ -0,0 +1,91 @@
+import sys
+
+from tutor.cli import theme
+from tutor.cli.commands import COMMAND_MAP, ShellContext
+from tutor.cli.logo import print_welcome
+from tutor.cli.video_commands import cmd_video, cmd_vsessions
+
+COMMAND_MAP["/video"] = cmd_video
+COMMAND_MAP["/vsessions"] = cmd_vsessions
+
+
+def _build_prompt(ctx: ShellContext) -> str:
+    p = ctx.player
+    if p is None or p._state == "STOPPED":
+        return f"{theme.CYAN}LearnX{theme.RESET} > "
+    icon = {"PLAYING": "▶", "PAUSED": "⏸", "ASKING": "?", "ANSWERING": "⟳"}.get(p._state, "·")
+    if p._current_idx < len(p.units):
+        unit = p.units[p._current_idx]
+        concept = unit.concept[:22]
+        idx_str = f"{p._current_idx + 1}/{len(p.units)}"
+        return f"{theme.CYAN}LearnX{theme.RESET} [{icon} {idx_str}  {concept}] > "
+    return f"{theme.CYAN}LearnX{theme.RESET} [{icon}] > "
+
+
+def run_shell() -> None:
+    _setup_utf8()
+    _prime_ffmpeg()
+    print_welcome()
+    ctx = ShellContext()
+
+    while True:
+        try:
+            line = input(_build_prompt(ctx)).strip()
+        except (KeyboardInterrupt, EOFError):
+            print()
+            _graceful_exit(ctx)
+            break
+
+        if not line:
+            continue
+
+        # Bare text while a session is active → route as /ask
+        if not line.startswith("/") and ctx.player and ctx.player._state not in ("STOPPED", None):
+            from tutor.cli.commands import cmd_ask
+
+            cmd_ask(line.split(), ctx)
+            continue
+
+        parts = line.split()
+        cmd = parts[0].lower() if parts else ""
+        tokens = parts[1:]
+
+        if cmd not in COMMAND_MAP:
+            print(theme.yellow(f"  Unknown command: {cmd}  — type /help for a list."))
+            continue
+
+        handler = COMMAND_MAP[cmd]
+        if handler is None:
+            _graceful_exit(ctx)
+            break
+
+        handler(tokens, ctx)
+
+
+def _graceful_exit(ctx: ShellContext) -> None:
+    if ctx.player and ctx.player._state not in ("STOPPED",):
+        ctx.player._quit()
+        if ctx.player_thread:
+            ctx.player_thread.join(timeout=2.0)
+    print(theme.dim("  Goodbye!\n"))
+
+
+def _prime_ffmpeg() -> None:
+    """Inject ffmpeg into PATH before pydub is imported so its warning never fires."""
+    try:
+        from tutor.config import _check_ffmpeg
+
+        _check_ffmpeg()
+    except Exception:
+        pass
+
+
+def _setup_utf8() -> None:
+    if hasattr(sys.stdout, "buffer"):
+        import io
+
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "buffer"):
+        import io
+
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")

tutor/cli/shell_context.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tutor.player.player import TutorPlayer
+
+
+@dataclass
+class ShellContext:
+    player: TutorPlayer | None = None
+    player_thread: threading.Thread | None = None
+    last_units_dir: Path | None = None
+    current_session: str | None = None
+    last_video: Path | None = None

tutor/cli/theme.py

@@ -0,0 +1,39 @@
+import os
+import sys
+
+# Enable ANSI escape codes on Windows 10+
+if sys.platform == "win32":
+    os.system("")
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+
+RED = "\033[91m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+
+
+def red(s: str) -> str:
+    return f"{RED}{s}{RESET}"
+
+
+def green(s: str) -> str:
+    return f"{GREEN}{s}{RESET}"
+
+
+def yellow(s: str) -> str:
+    return f"{YELLOW}{s}{RESET}"
+
+
+def cyan(s: str) -> str:
+    return f"{CYAN}{s}{RESET}"
+
+
+def bold(s: str) -> str:
+    return f"{BOLD}{s}{RESET}"
+
+
+def dim(s: str) -> str:
+    return f"{DIM}{s}{RESET}"

tutor/cli/video_commands.py

@@ -0,0 +1,123 @@
+"""
+Shell command handlers for the video pipeline.
+Separate from commands.py so the audio pipeline file stays under 400 lines.
+"""
+
+import logging
+from functools import partial
+from pathlib import Path
+
+from tutor.cli import theme
+from tutor.cli.commands import AUDIO_DIR, ShellContext
+
+log = logging.getLogger(__name__)
+
+VIDEO_DIR = Path("video")
+
+
+def cmd_video(tokens: list[str], ctx: ShellContext) -> None:
+    """Usage: /video [session-name]
+    Generate MP4 video for a session. Requires /generate to have run first."""
+    if not tokens:
+        if ctx.current_session:
+            session = ctx.current_session
+        else:
+            print(theme.red("  Usage: /video <session-name>"))
+            return
+    else:
+        session = tokens[0]
+
+    audio_session_dir = AUDIO_DIR / session
+    try:
+        _assert_audio_ready(audio_session_dir)
+    except Exception as e:
+        print(theme.red(f"  Error: {e}"))
+        return
+
+    mp4_path = VIDEO_DIR / session / "full_session.mp4"
+    if mp4_path.exists():
+        if not _confirm_overwrite(mp4_path):
+            print(theme.dim("  Skipped."))
+            return
+
+    try:
+        _run_video_pipeline(session, ctx)
+    except KeyboardInterrupt:
+        print(theme.yellow("\n  Cancelled."))
+    except Exception as e:
+        print(theme.red(f"\n  Error: {e}\n"))
+        log.exception("Video pipeline failed for session %s", session)
+
+
+def cmd_vsessions(tokens: list[str], ctx: ShellContext) -> None:
+    """Usage: /vsessions — list sessions that have a completed video."""
+    if not VIDEO_DIR.exists():
+        print(theme.dim("  No video sessions yet. Use /video <session> to create one."))
+        return
+
+    sessions = sorted(
+        d for d in VIDEO_DIR.iterdir() if d.is_dir() and (d / "full_session.mp4").exists()
+    )
+    if not sessions:
+        print(theme.dim("  No completed videos yet. Use /video <session-name>."))
+        return
+
+    print()
+    for s in sessions:
+        mp4 = s / "full_session.mp4"
+        size_mb = mp4.stat().st_size / 1_048_576
+        print(f"  {theme.cyan(s.name):<30} {theme.green('[mp4]')}  {size_mb:.0f} MB")
+    print(theme.dim("\n  Play with your video player: vlc video/<session>/full_session.mp4"))
+    print()
+
+
+def _run_video_pipeline(session: str, ctx: ShellContext) -> None:
+    """Resolve paths and run the full visual pipeline."""
+    from tutor.config import load_config
+    from tutor.infra import llm as _llm
+    from tutor.visual import run_visual_pipeline
+
+    config = load_config()
+    provider = "groq"
+    llm_fn = partial(_llm.chat, provider=provider, config=config)
+    video_dir = VIDEO_DIR / session
+    video_dir.mkdir(parents=True, exist_ok=True)
+
+    audio_dir = AUDIO_DIR / session
+    units = list((audio_dir / "tutorial_units").glob("unit_*.mp3"))
+    print(f"\n  Resolving session {theme.bold(session)}...")
+    print(f"  Found {len(units)} units. Starting visual pipeline.")
+
+    result = run_visual_pipeline(session, audio_dir, video_dir, llm_fn, difficulty="beginner")
+    ctx.last_video = result
+    ctx.current_session = session
+
+
+def _assert_audio_ready(audio_session_dir: Path) -> None:
+    """Raise ValueError if the audio session is not ready."""
+    if not audio_session_dir.exists():
+        raise ValueError(
+            f"Session '{audio_session_dir.name}' not found in {AUDIO_DIR}/.\n"
+            "  Run /generate first to produce audio."
+        )
+    units_json = audio_session_dir / "tutorial.units.json"
+    if not units_json.exists():
+        raise ValueError(
+            f"tutorial.units.json not found in {audio_session_dir}.\n"
+            "  The audio pipeline must complete before running /video."
+        )
+    mp3s = list((audio_session_dir / "tutorial_units").glob("unit_*.mp3"))
+    if not mp3s:
+        raise ValueError(
+            f"No MP3 files found in {audio_session_dir / 'tutorial_units'}.\n"
+            "  Run /generate (without --script-only) to produce audio."
+        )
+
+
+def _confirm_overwrite(mp4_path: Path) -> bool:
+    """Prompt if full_session.mp4 already exists. Returns True to proceed."""
+    try:
+        answer = input("  Session already has a video. Regenerate? [y/N]: ").strip().lower()
+        return answer == "y"
+    except (EOFError, KeyboardInterrupt):
+        return False

tutor/config.py

@@ -0,0 +1,122 @@
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from tutor.exceptions import ConfigError
+
+
+@dataclass
+class Config:
+    groq_api_key: str = ""
+    openrouter_api_key: str = ""
+    default_provider: str = "groq"
+
+
+def load_config() -> Config:
+    load_dotenv(Path(__file__).parent / ".env")
+    return Config(
+        groq_api_key=os.getenv("GROQ_API_KEY", ""),
+        openrouter_api_key=os.getenv("OPENROUTER_API_KEY", ""),
+    )
+
+
+def preflight(input_path: str, provider: str, mode: str) -> Config:
+    config = load_config()
+
+    if mode not in ("inspect", "dry-run", "script-only"):
+        if input_path is None:
+            raise ConfigError(
+                "No input file specified.\n  Usage: python tutor.py <input.md> [options]"
+            )
+
+    if input_path is not None:
+        p = Path(input_path)
+        if not p.exists():
+            raise ConfigError(
+                f"Input file not found: {input_path}\n  Check the path and try again."
+            )
+        if p.suffix.lower() != ".md":
+            raise ConfigError(
+                f"Input file must be a .md file, got: {p.suffix}\n  Only Markdown files are supported."
+            )
+
+    if provider == "groq" and not config.groq_api_key:
+        raise ConfigError(
+            "GROQ_API_KEY not set.\n"
+            "  Add it to tutor/.env: GROQ_API_KEY=gsk_...\n"
+            "  Get a free key at: console.groq.com"
+        )
+
+    if provider == "openrouter" and not config.openrouter_api_key:
+        raise ConfigError(
+            "OPENROUTER_API_KEY not set.\n"
+            "  Add it to tutor/.env: OPENROUTER_API_KEY=sk-or-...\n"
+            "  Sign up at: openrouter.ai"
+        )
+
+    if mode not in ("script-only", "dry-run", "inspect") and input_path:
+        out_parent = Path(input_path).parent
+        if not os.access(out_parent, os.W_OK):
+            raise ConfigError(
+                f"Output directory is not writable: {out_parent}\n"
+                "  Check permissions or specify a different --output path."
+            )
+
+    if mode == "generate":
+        _check_ffmpeg()
+
+    return config
+
+
+def _check_ffmpeg() -> None:
+    try:
+        subprocess.run(
+            ["ffmpeg", "-version"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+        return
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        pass
+
+    # PATH doesn't have ffmpeg — probe common Windows install layouts.
+    if sys.platform == "win32":
+        _winget_pkgs = Path.home() / "AppData/Local/Microsoft/WinGet/Packages"
+        candidates: list[Path] = [
+            Path("C:/ffmpeg/bin/ffmpeg.exe"),
+            *Path("C:/ffmpeg").glob("*/bin/ffmpeg.exe"),
+            Path("C:/Program Files/ffmpeg/bin/ffmpeg.exe"),
+            *Path("C:/Program Files/ffmpeg").glob("*/bin/ffmpeg.exe"),
+            Path("C:/tools/ffmpeg/bin/ffmpeg.exe"),
+            *(_winget_pkgs.glob("Gyan.FFmpeg*/*/bin/ffmpeg.exe") if _winget_pkgs.exists() else []),
+            *(_winget_pkgs.glob("*/ffmpeg*/bin/ffmpeg.exe") if _winget_pkgs.exists() else []),
+        ]
+        for candidate in candidates:
+            if candidate.exists():
+                _inject_ffmpeg(candidate.parent)
+                return
+
+    raise ConfigError(
+        "ffmpeg not found in PATH.\n"
+        "  Install with: winget install ffmpeg\n"
+        "  Or add its bin\\ folder to your system PATH and restart the terminal."
+    )
+
+
+def _inject_ffmpeg(bin_dir: Path) -> None:
+    """Add a discovered ffmpeg directory to the process PATH so pydub finds it."""
+    os.environ["PATH"] = str(bin_dir) + os.pathsep + os.environ.get("PATH", "")
+    # Patch pydub's runtime converter path if pydub is already imported.
+    try:
+        import pydub
+
+        pydub.AudioSegment.converter = str(bin_dir / "ffmpeg.exe")
+        pydub.AudioSegment.ffmpeg = str(bin_dir / "ffmpeg.exe")
+        pydub.AudioSegment.ffprobe = str(bin_dir / "ffprobe.exe")
+    except Exception:
+        pass

tutor/conftest.py

@@ -0,0 +1,5 @@
+import sys
+from pathlib import Path
+
+# Allow `from tutor.x import y` when pytest is run from inside the tutor/ directory
+sys.path.insert(0, str(Path(__file__).parent.parent))

tutor/constants.py

@@ -0,0 +1,82 @@
+# Audio
+WPM = 130
+SILENCE_BREATH_MS = 150
+SILENCE_TURN_MS = 500
+SILENCE_UNIT_MS = 1200
+SILENCE_SESSION_MS = 800
+TTS_SEMAPHORE_LIMIT = 8
+
+# Voices
+VOICE_TUTOR = "en-US-GuyNeural"
+VOICE_STUDENT = "en-US-JennyNeural"
+VOICE_COTUTOR = "en-US-SaraNeural"
+RATE_TUTOR = "+0%"
+RATE_STUDENT = "+5%"
+RATE_COTUTOR = "+0%"
+
+# Ingestion
+STRATEGY_A_TOKEN_LIMIT = 6_000
+STRATEGY_B_TOKEN_LIMIT = 60_000
+MAX_CHUNK_TOKENS = 4_000
+MIN_CHUNK_TOKENS = 50
+SUMMARY_CACHE_DIR = ".tutor_cache"
+STRATEGY_C_WINDOW_TOKENS = 2_000
+STRATEGY_C_OVERLAP_TOKENS = 200
+
+# Complexity
+WORDS_PER_COMPLEXITY: dict[int, int] = {1: 200, 2: 380, 3: 580}
+OVERHEAD_WORDS = 200  # intro + transitions + outro
+
+# Player
+PLAYER_POLL_HZ = 10
+PLAYER_BAR_WIDTH = 40
+
+# Difficulty
+DIFFICULTY_CONTEXT: dict[str, str] = {
+    "beginner": (
+        "The student has never written Java before. "
+        "Prioritise Tier 0-2 concepts. Analogies are mandatory. "
+        "Set max complexity to 2. Word budget multiplier: 1.3."
+    ),
+    "intermediate": (
+        "The student has written Java for 3 months. "
+        "Assume JVM basics are known. Use Tier 1-4 concepts. "
+        "Word budget multiplier: 1.0."
+    ),
+    "advanced": (
+        "The student knows OOP but makes design-level mistakes. "
+        "Focus on Tier 3-6: contracts, concurrency, edge cases. "
+        "Word budget multiplier: 0.8."
+    ),
+}
+
+DIFFICULTY_MULTIPLIERS: dict[str, float] = {
+    "beginner": 1.3,
+    "intermediate": 1.0,
+    "advanced": 0.8,
+}
+
+# Source/summarise token limits live in tutor/llm_config.toml (limits section)
+
+# Versioning
+PROMPT_VERSION = "v1"
+MAX_UNITS = 8
+MIN_UNITS = 3
+DEFAULT_DURATION_MIN = 20
+DEFAULT_DIFFICULTY = "beginner"
+DEFAULT_FORMAT = "tutor-student"
+DEFAULT_SUBJECT = "java"
+
+# Code-to-speech substitutions (pattern, replacement)
+CODE_SUBSTITUTIONS = [
+    (r"List<String>", "a List of Strings"),
+    (r"HashMap<(\w+),\s*(\w+)>", r"a HashMap from \1 to \2"),
+    (r"!=", "not equal to"),
+    (r"(?<![=!<>])==(?![=])", "double equals"),
+    (r"\.equals\(", "dot equals("),
+    (r"@(\w+)", r"\1 annotation"),
+    (r"(\w+)\[\]", r"\1 array"),
+    (r"NullPointerException", "Null Pointer Exception"),
+    (r"StackOverflowError", "Stack Overflow Error"),
+    (r"IllegalArgumentException", "Illegal Argument Exception"),
+]

tutor/exceptions.py

@@ -0,0 +1,26 @@
+class TutorError(Exception):
+    """Base for all tutor AI errors."""
+
+
+class IngestionError(TutorError):
+    """Raised when doc parsing or chunking fails."""
+
+
+class LLMError(TutorError):
+    """Raised when an LLM call fails or returns unparseable output."""
+
+
+class TTSError(TutorError):
+    """Raised when audio rendering fails."""
+
+
+class PlayerError(TutorError):
+    """Raised when the interactive player encounters an unrecoverable state."""
+
+
+class ConfigError(TutorError):
+    """Raised when required config (API key, ffmpeg) is missing."""
+
+
+class VideoError(TutorError):
+    """Raised when any step of the video pipeline fails."""

tutor/generation/assembler.py

@@ -0,0 +1,81 @@
+from tutor.audio import sanitizer
+from tutor.models import DialogueLine, TeachingUnit
+
+
+def assemble(
+    units: list[TeachingUnit],
+    all_lines: list[list[DialogueLine]],
+    fmt: str,
+    doc_title: str,
+    mode: str = "conversation",
+) -> list[DialogueLine]:
+    result: list[DialogueLine] = []
+
+    result.extend(_build_intro(units, doc_title, mode))
+
+    for i, (unit, lines) in enumerate(zip(units, all_lines, strict=False)):
+        result.extend(lines)
+        if mode == "conversation" and i < len(units) - 1:
+            next_concept = units[i + 1].concept if i + 1 < len(units) else ""
+            result.append(
+                DialogueLine(
+                    speaker="MAYA",
+                    text=f"Alright, let's move on to the next one: {next_concept}.",
+                    unit_number=unit.unit,
+                )
+            )
+
+    result.extend(_build_outro(units, doc_title, mode))
+
+    for line in result:
+        line.text = sanitizer.apply(line.text)
+
+    return result
+
+
+def _build_intro(units: list[TeachingUnit], doc_title: str, mode: str) -> list[DialogueLine]:
+    if mode == "explain":
+        text = (
+            f"Let's walk through {doc_title}. "
+            f"I'll cover {len(units)} section{'s' if len(units) != 1 else ''} from top to bottom, "
+            f"following the document as you read along."
+        )
+        return [DialogueLine(speaker="ALEX", text=text, unit_number=0)]
+    else:
+        concepts = ", ".join(u.concept for u in units)
+        alex_text = (
+            f"Welcome. In this session we're covering {doc_title}. "
+            f"We'll walk through {len(units)} concept{'s' if len(units) != 1 else ''} step by step: {concepts}."
+        )
+        maya_text = (
+            "We'll explain each one clearly, with analogies, so by the end you'll have "
+            "a solid picture of how it all fits together. Let's get into it."
+        )
+        return [
+            DialogueLine(speaker="ALEX", text=alex_text, unit_number=0),
+            DialogueLine(speaker="MAYA", text=maya_text, unit_number=0),
+        ]
+
+
+def _build_outro(units: list[TeachingUnit], doc_title: str, mode: str) -> list[DialogueLine]:
+    if mode == "explain":
+        text = (
+            f"That covers all {len(units)} section{'s' if len(units) != 1 else ''} of {doc_title}. "
+            f"You can replay any section with the replay command, or ask a question with ask."
+        )
+        return [DialogueLine(speaker="ALEX", text=text, unit_number=-1)]
+    else:
+        hooks = ". ".join(u.memory_hook for u in units if u.memory_hook)
+        alex_text = (
+            f"That's everything for {doc_title}. "
+            f"We covered {len(units)} concept{'s' if len(units) != 1 else ''} today. "
+            f"Here's what to hold onto: {hooks}."
+        )
+        maya_text = (
+            "If any of those didn't fully click, replay that unit and let it settle. "
+            "These are the ideas that show up constantly in real Java code."
+        )
+        return [
+            DialogueLine(speaker="ALEX", text=alex_text, unit_number=-1),
+            DialogueLine(speaker="MAYA", text=maya_text, unit_number=-1),
+        ]

tutor/generation/curriculum.py

@@ -0,0 +1,97 @@
+import logging
+
+from tutor.constants import (
+    DIFFICULTY_CONTEXT,
+    DIFFICULTY_MULTIPLIERS,
+    OVERHEAD_WORDS,
+    WORDS_PER_COMPLEXITY,
+    WPM,
+)
+from tutor.exceptions import LLMError
+from tutor.infra.llm import LLMFn, load_prompt, parse_json_response
+from tutor.models import Chunk, DocProfile, TeachingUnit
+
+log = logging.getLogger(__name__)
+
+
+def plan(
+    chunks: list[Chunk],
+    profile: DocProfile,
+    duration_min: int,
+    llm_fn: LLMFn,
+    difficulty: str = "beginner",
+    topic: str | None = None,
+) -> list[TeachingUnit]:
+    summaries = "\n".join(f"[{c.chunk_id}] {c.summary}" for c in chunks)
+    difficulty_context = DIFFICULTY_CONTEXT.get(difficulty, DIFFICULTY_CONTEXT["beginner"])
+
+    prompt = load_prompt("curriculum.txt").format(
+        doc_title=profile.filepath,
+        duration_min=duration_min,
+        difficulty=difficulty,
+        difficulty_context=difficulty_context,
+        summaries=summaries,
+    )
+
+    if topic:
+        topic_instruction = (
+            f'IMPORTANT: You must include a unit that covers the topic "{topic}". '
+            "If the source document does not mention it, create a unit that acknowledges "
+            "it is out of scope but explains why it matters in relation to what was covered."
+        )
+        prompt = topic_instruction + "\n\n" + prompt
+
+    messages = [{"role": "user", "content": prompt}]
+    log.info("Planning curriculum for %d chunks, %d min target", len(chunks), duration_min)
+
+    raw = llm_fn(messages, call_type="curriculum")
+    try:
+        data = parse_json_response(raw)
+    except LLMError:
+        retry_messages = messages + [
+            {"role": "assistant", "content": raw},
+            {
+                "role": "user",
+                "content": "Your previous response could not be parsed as JSON. Reply with the raw JSON array only, no other text.",
+            },
+        ]
+        raw = llm_fn(retry_messages, call_type="curriculum")
+        data = parse_json_response(raw)
+
+    if not isinstance(data, list) or len(data) == 0:
+        raise LLMError("Curriculum planner returned no units")
+
+    total_budget = duration_min * WPM - OVERHEAD_WORDS
+    total_complexity = sum(int(u.get("complexity", 2)) for u in data)
+    if total_complexity == 0:
+        total_complexity = len(data)
+    multiplier = DIFFICULTY_MULTIPLIERS.get(difficulty, 1.0)
+    base = total_budget / total_complexity
+
+    units: list[TeachingUnit] = []
+    for i, u in enumerate(data):
+        complexity = max(1, min(3, int(u.get("complexity", 2))))
+        word_budget = max(
+            round(base * complexity * multiplier),
+            WORDS_PER_COMPLEXITY[1],  # floor: min 200 words even for advanced
+        )
+        units.append(
+            TeachingUnit(
+                unit=i + 1,
+                concept=u.get("concept", f"Unit {i + 1}"),
+                source_sections=u.get("source_sections", []),
+                complexity=complexity,
+                word_budget=word_budget,
+                key_facts=u.get("key_facts", []),
+                common_misconception=u.get("common_misconception", ""),
+                good_analogy=u.get("good_analogy", ""),
+                question_style=u.get("question_style", "recall"),
+                memory_hook=u.get("memory_hook", ""),
+                prerequisite_concepts=u.get("prerequisite_concepts", []),
+                js_contrast=u.get("js_contrast", ""),
+                production_relevance=u.get("production_relevance", ""),
+            )
+        )
+
+    log.info("Curriculum planned: %d units", len(units))
+    return units