learnx-cli 0.3.0__py3-none-any.whl

tutor/tests/visual/test_visual_pipeline.py

@@ -0,0 +1,270 @@
+"""
+Tests for tutor/visual/__init__.py helpers:
+    _doc_title_from_units, _load_all_lines, _mp3_duration, _format_duration
+"""
+
+import json
+import subprocess
+
+import pytest
+
+from tutor.models import DialogueLine
+from tutor.visual import _doc_title_from_units, _format_duration, _load_all_lines, _mp3_duration
+
+# ── _doc_title_from_units ────────────────────────────────────────────────────
+
+
+def test_doc_title_returns_first_concept(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(
+        json.dumps([{"concept": "Interfaces"}, {"concept": "Abstract Classes"}]),
+        encoding="utf-8",
+    )
+    assert _doc_title_from_units(units_json) == "Interfaces"
+
+
+def test_doc_title_fallback_when_empty_list(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text("[]", encoding="utf-8")
+    assert _doc_title_from_units(units_json) == "Tutorial"
+
+
+def test_doc_title_fallback_when_file_missing(tmp_path):
+    missing = tmp_path / "nonexistent.json"
+    assert _doc_title_from_units(missing) == "Tutorial"
+
+
+def test_doc_title_fallback_when_malformed_json(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text("this is not JSON", encoding="utf-8")
+    assert _doc_title_from_units(units_json) == "Tutorial"
+
+
+def test_doc_title_uses_concept_key(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    # "concept" key missing — falls back to "Tutorial"
+    units_json.write_text(json.dumps([{"name": "Something Else"}]), encoding="utf-8")
+    assert _doc_title_from_units(units_json) == "Tutorial"
+
+
+# ── _load_all_lines — from units JSON lines field ────────────────────────────
+
+
+def test_load_all_lines_from_units_json(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_data = [
+        {
+            "concept": "Interfaces",
+            "lines": [
+                {"speaker": "ALEX", "text": "What is an interface?", "unit_number": 1},
+                {"speaker": "MAYA", "text": "A contract.", "unit_number": 1},
+            ],
+        }
+    ]
+    units_json.write_text(json.dumps(units_data), encoding="utf-8")
+    lines = _load_all_lines(units_json)
+
+    assert len(lines) == 2
+    assert all(isinstance(line, DialogueLine) for line in lines)
+    assert lines[0].speaker == "ALEX"
+    assert lines[1].speaker == "MAYA"
+
+
+def test_load_all_lines_from_multiple_units(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_data = [
+        {
+            "concept": "Unit1",
+            "lines": [
+                {"speaker": "ALEX", "text": "Line from unit 1", "unit_number": 1},
+            ],
+        },
+        {
+            "concept": "Unit2",
+            "lines": [
+                {"speaker": "MAYA", "text": "Line from unit 2", "unit_number": 2},
+                {"speaker": "ALEX", "text": "Another unit 2 line", "unit_number": 2},
+            ],
+        },
+    ]
+    units_json.write_text(json.dumps(units_data), encoding="utf-8")
+    lines = _load_all_lines(units_json)
+
+    assert len(lines) == 3
+    assert lines[0].unit_number == 1
+    assert lines[1].unit_number == 2
+
+
+# ── _load_all_lines — fallback to tutorial.script.txt ───────────────────────
+
+
+def test_load_all_lines_fallback_to_script_txt(tmp_path):
+    """No 'lines' in JSON → falls back to tutorial.script.txt."""
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([{"concept": "Interfaces"}]), encoding="utf-8")
+
+    script_txt = tmp_path / "tutorial.script.txt"
+    script_txt.write_text(
+        "ALEX: What is an interface?\nMAYA: A contract between a class and the world.\n",
+        encoding="utf-8",
+    )
+    lines = _load_all_lines(units_json)
+
+    assert len(lines) == 2
+    assert lines[0].speaker == "ALEX"
+    assert lines[1].speaker == "MAYA"
+
+
+def test_load_all_lines_returns_empty_when_no_lines_no_script(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([{"concept": "X"}]), encoding="utf-8")
+    # No script file present
+    lines = _load_all_lines(units_json)
+    assert lines == []
+
+
+def test_load_all_lines_script_txt_filters_non_speaker_lines(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([{"concept": "X"}]), encoding="utf-8")
+
+    script_txt = tmp_path / "tutorial.script.txt"
+    script_txt.write_text(
+        "NARRATOR: This line should be ignored.\n"
+        "ALEX: Valid line.\n"
+        "  This is a blank-ish line.\n"
+        "MAYA: Another valid line.\n",
+        encoding="utf-8",
+    )
+    lines = _load_all_lines(units_json)
+    # NARRATOR is not a known speaker
+    speakers = {line.speaker for line in lines}
+    assert "NARRATOR" not in speakers
+    assert "ALEX" in speakers
+    assert "MAYA" in speakers
+
+
+def test_load_all_lines_empty_units_json_list(tmp_path):
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text("[]", encoding="utf-8")
+    lines = _load_all_lines(units_json)
+    assert lines == []
+
+
+def test_load_all_lines_script_assigns_units_sequentially(tmp_path):
+    """Lines from script.txt should be distributed across units."""
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(
+        json.dumps([{"concept": "A"}, {"concept": "B"}]),
+        encoding="utf-8",
+    )
+    script_txt = tmp_path / "tutorial.script.txt"
+    # 4 lines, 2 units → 2 per unit
+    script_txt.write_text(
+        "ALEX: Line 1\nMAYA: Line 2\nALEX: Line 3\nMAYA: Line 4\n",
+        encoding="utf-8",
+    )
+    lines = _load_all_lines(units_json)
+    assert len(lines) == 4
+    unit_numbers = {line.unit_number for line in lines}
+    # Should span at least 2 distinct unit numbers (1 and 2)
+    assert len(unit_numbers) >= 1
+
+
+# ── _mp3_duration ─────────────────────────────────────────────────────────────
+
+
+def test_mp3_duration_returns_float_on_success(monkeypatch, tmp_path):
+    fake_mp3 = tmp_path / "unit_01.mp3"
+    fake_mp3.touch()
+
+    def mock_run(cmd, **kwargs):
+        return subprocess.CompletedProcess(cmd, 0, b"45.321\n", b"")
+
+    monkeypatch.setattr(subprocess, "run", mock_run)
+    duration = _mp3_duration(fake_mp3)
+    assert duration == pytest.approx(45.321, abs=0.001)
+
+
+def test_mp3_duration_returns_zero_on_ffprobe_error(monkeypatch, tmp_path):
+    fake_mp3 = tmp_path / "unit_01.mp3"
+    fake_mp3.touch()
+
+    def failing_run(cmd, **kwargs):
+        raise FileNotFoundError("ffprobe not found")
+
+    monkeypatch.setattr(subprocess, "run", failing_run)
+    assert _mp3_duration(fake_mp3) == 0.0
+
+
+def test_mp3_duration_returns_zero_on_bad_output(monkeypatch, tmp_path):
+    fake_mp3 = tmp_path / "unit_01.mp3"
+    fake_mp3.touch()
+
+    def mock_run(cmd, **kwargs):
+        return subprocess.CompletedProcess(cmd, 0, b"N/A\n", b"")
+
+    monkeypatch.setattr(subprocess, "run", mock_run)
+    assert _mp3_duration(fake_mp3) == 0.0
+
+
+def test_mp3_duration_returns_zero_on_timeout(monkeypatch, tmp_path):
+    fake_mp3 = tmp_path / "unit_01.mp3"
+    fake_mp3.touch()
+
+    def timeout_run(cmd, **kwargs):
+        raise subprocess.TimeoutExpired(cmd, 10)
+
+    monkeypatch.setattr(subprocess, "run", timeout_run)
+    assert _mp3_duration(fake_mp3) == 0.0
+
+
+# ── _format_duration ─────────────────────────────────────────────────────────
+
+
+def test_format_duration_zero():
+    assert _format_duration(0) == "0:00"
+
+
+def test_format_duration_one_minute():
+    assert _format_duration(60) == "1:00"
+
+
+def test_format_duration_90_seconds():
+    assert _format_duration(90) == "1:30"
+
+
+def test_format_duration_pads_seconds():
+    assert _format_duration(65) == "1:05"
+
+
+def test_format_duration_over_one_hour():
+    assert _format_duration(3661) == "61:01"
+
+
+def test_format_duration_fractional_truncated():
+    """Fractional seconds should be truncated to int, not rounded."""
+    assert _format_duration(59.9) == "0:59"
+
+
+# ── _UNIT_MP3_RE ──────────────────────────────────────────────────────────────
+
+
+def test_unit_mp3_re_matches_valid_stems():
+    from tutor.visual import _UNIT_MP3_RE
+
+    assert _UNIT_MP3_RE.match("unit_01")
+    assert _UNIT_MP3_RE.match("unit_10")
+    assert _UNIT_MP3_RE.match("unit_99")
+
+
+def test_unit_mp3_re_rejects_intro():
+    from tutor.visual import _UNIT_MP3_RE
+
+    assert _UNIT_MP3_RE.match("unit_00_intro") is None
+
+
+def test_unit_mp3_re_rejects_non_unit_names():
+    from tutor.visual import _UNIT_MP3_RE
+
+    assert _UNIT_MP3_RE.match("tutorial") is None
+    assert _UNIT_MP3_RE.match("outro") is None

tutor/tutor.py

@@ -0,0 +1,365 @@
+import argparse
+import asyncio
+import io
+import json
+import logging
+import shutil
+import sys
+from dataclasses import asdict
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tutor.player.player import TutorPlayer
+
+from tutor import inspector
+from tutor.audio import audio_builder
+from tutor.config import preflight
+from tutor.constants import (
+    DEFAULT_DIFFICULTY,
+    DEFAULT_DURATION_MIN,
+    DEFAULT_FORMAT,
+    DEFAULT_SUBJECT,
+    WPM,
+)
+from tutor.exceptions import TutorError
+from tutor.generation import assembler, curriculum, dialogue, narrator
+from tutor.infra import llm
+from tutor.ingestion import chunker, doc_analyzer, summarizer
+from tutor.models import Chunk, DialogueLine, DocProfile, TeachingUnit
+
+
+def main() -> None:
+    # Force UTF-8 output on Windows so LLM-generated unicode (≠, →, etc.) doesn't crash.
+    # Done here (not at module level) so pytest's stdout capture isn't affected.
+    if hasattr(sys.stdout, "buffer"):
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "buffer"):
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+
+    # Detect "play" subcommand before building the main parser — argparse
+    # cannot handle a positional that is either a subcommand or a file path.
+    if len(sys.argv) > 1 and sys.argv[1] == "play":
+        _run_play()
+        return
+
+    parser = argparse.ArgumentParser(prog="tutor", description="Tutor AI — Java audio sessions")
+    parser.add_argument("input", nargs="?", help="Path to input .md file")
+    parser.add_argument("--output", default="tutorial.mp3")
+    parser.add_argument("--provider", default="groq")
+    parser.add_argument("--duration", type=int, default=DEFAULT_DURATION_MIN)
+    parser.add_argument("--format", default=DEFAULT_FORMAT, dest="fmt")
+    parser.add_argument("--difficulty", default=DEFAULT_DIFFICULTY)
+    parser.add_argument("--units", type=int, default=None)
+    parser.add_argument("--subject", default=DEFAULT_SUBJECT)
+    parser.add_argument("--topic", default=None)
+    parser.add_argument("--play", action="store_true")
+    parser.add_argument("--script-only", action="store_true", dest="script_only")
+    parser.add_argument("--dry-run", action="store_true", dest="dry_run")
+    parser.add_argument("--inspect", action="store_true")
+    parser.add_argument("--show-summaries", action="store_true", dest="show_summaries")
+    parser.add_argument("--no-cache", action="store_true", dest="no_cache")
+    parser.add_argument("--verbose", action="store_true")
+    parser.add_argument("--debug", action="store_true")
+    mode_group = parser.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--explain",
+        action="store_true",
+        help="Narrate the document top-to-bottom (read-along mode)",
+    )
+    mode_group.add_argument(
+        "--conversation", action="store_true", help="Concept-driven dialogue (default)"
+    )
+
+    args = parser.parse_args()
+    _setup_logging(args)
+
+    try:
+        cmd_generate(args)
+    except TutorError as e:
+        print(f"\n✗ {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _run_play() -> None:
+    parser = argparse.ArgumentParser(prog="tutor play")
+    parser.add_argument("audio_file")
+    parser.add_argument("--provider", default="groq")
+    parser.add_argument("--no-qa", action="store_true", dest="no_qa")
+    parser.add_argument("--verbose", action="store_true")
+    parser.add_argument("--debug", action="store_true")
+    args = parser.parse_args(sys.argv[2:])
+    _setup_logging(args)
+    try:
+        cmd_play(args)
+    except TutorError as e:
+        print(f"\n✗ {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_generate(args: argparse.Namespace) -> None:
+    pipeline_mode = _mode(args)
+    config = preflight(args.input, args.provider, pipeline_mode)
+    llm_fn = partial(llm.chat, provider=args.provider, config=config)
+
+    if args.no_cache:
+        cache_dir = Path(".tutor_cache")
+        if cache_dir.exists():
+            shutil.rmtree(cache_dir)
+            print("Cache cleared (all summaries and dialogues will be regenerated).")
+
+    profile = doc_analyzer.analyze(args.input)
+    chunks = chunker.chunk(Path(args.input).read_text(encoding="utf-8"), profile)
+
+    if args.inspect:
+        _run_inspect(args, profile, chunks)
+        return
+
+    if args.subject not in ("java", "general"):
+        print(f"Warning: --subject {args.subject!r} is not supported yet; proceeding as 'general'.")
+
+    doc_title = Path(args.input).stem.replace("-", " ").replace("_", " ").title()
+    is_explain = getattr(args, "explain", False)
+
+    if is_explain:
+        _save_chunks(chunks, args.output)
+        units, all_lines = narrator.narrate_all(chunks, doc_title, llm_fn)
+        script = assembler.assemble(units, all_lines, "explain", doc_title, mode="explain")
+    else:
+        print(f"Summarising {len(chunks)} chunk(s)...")
+        chunks = summarizer.summarize_all(chunks, llm_fn)
+        _save_chunks(chunks, args.output)
+
+        print("Planning curriculum...")
+        units = curriculum.plan(chunks, profile, args.duration, llm_fn, args.difficulty, args.topic)
+        if args.units:
+            units = units[: args.units]
+
+        if args.dry_run:
+            inspector.report_curriculum(units, chunks, args.duration)
+            return
+
+        print(f"Generating dialogue for {len(units)} unit(s)...")
+        all_lines = []
+        for i, u in enumerate(units, 1):
+            print(f"  [{i}/{len(units)}] {u.concept}")
+            all_lines.append(dialogue.generate(u, chunks, args.fmt, llm_fn, args.difficulty))
+        script = assembler.assemble(units, all_lines, args.fmt, doc_title)
+
+    _print_duration_estimate(script)
+
+    if args.script_only:
+        _run_script_only(script)
+        return
+
+    _run_audio(args, units, script)
+
+    if getattr(args, "play", False):
+        cmd_play(args)
+
+
+def _run_inspect(args: argparse.Namespace, profile: DocProfile, chunks: list[Chunk]) -> None:
+    inspector.report_ingestion(profile, chunks)
+    if args.show_summaries:
+        for c in chunks:
+            print(f"\n--- {c.chunk_id} ---\n{c.summary}")
+
+
+def _run_script_only(script: list[DialogueLine]) -> None:
+    for line in script:
+        print(f"{line.speaker}: {line.text}")
+
+
+def _save_chunks(chunks: list[Chunk], output_path: str) -> None:
+    chunks_path = Path(output_path).parent / "tutorial.chunks.json"
+    with open(chunks_path, "w", encoding="utf-8") as f:
+        json.dump([asdict(c) for c in chunks], f, indent=2, ensure_ascii=False)
+
+
+def _run_audio(
+    args: argparse.Namespace, units: list[TeachingUnit], script: list[DialogueLine]
+) -> None:
+    script_path = Path(args.output).with_suffix(".script.txt")
+    units_dir = str(Path(args.output).parent / "tutorial_units")
+
+    with open(script_path, "w", encoding="utf-8") as f:
+        for line in script:
+            f.write(f"{line.speaker}: {line.text}\n")
+    print(f"Script saved: {script_path}")
+    print("Generating audio — this takes 2–4 minutes for a 20-min session...")
+
+    asyncio.run(audio_builder.build(script, args.output, units_dir))
+
+    units_json_path = Path(args.output).parent / "tutorial.units.json"
+    with open(units_json_path, "w", encoding="utf-8") as f:
+        json.dump([asdict(u) for u in units], f, indent=2, ensure_ascii=False)
+
+    print("\nDone.")
+    print(f"  Audio:  {args.output}")
+    print(f"  Units:  {units_dir}/")
+    print(f"  Script: {script_path}")
+    print(f"  Meta:   {units_json_path}")
+
+
+def cmd_play(args: argparse.Namespace) -> None:
+    player = _build_player(args)
+    player.run()
+
+
+def _build_player(args: argparse.Namespace) -> "TutorPlayer":
+    """Build and return a configured TutorPlayer without starting it."""
+    import json
+    from datetime import datetime
+    from functools import partial as _partial
+
+    from tutor.config import load_config
+    from tutor.exceptions import PlayerError
+    from tutor.infra import llm as _llm
+    from tutor.models import Chunk, SessionLog, TeachingUnit
+    from tutor.player.player import TutorPlayer
+
+    _log = logging.getLogger(__name__)
+
+    if hasattr(args, "audio_file"):
+        audio_path = Path(args.audio_file)
+        units_dir = audio_path if audio_path.is_dir() else audio_path.parent / "tutorial_units"
+    else:
+        units_dir = Path(args.output).parent / "tutorial_units"
+
+    if not units_dir.exists():
+        raise PlayerError(
+            f"tutorial_units/ not found at {units_dir}.\n  Run generation first or use /generate."
+        )
+
+    unit_files = sorted(units_dir.glob("*.mp3"))
+    if not unit_files:
+        raise PlayerError(f"No .mp3 files found in {units_dir}")
+
+    units_json = units_dir.parent / "tutorial.units.json"
+    if units_json.exists():
+        with open(units_json, encoding="utf-8") as f:
+            raw_units = json.load(f)
+        for u in raw_units:
+            u.setdefault("prerequisite_concepts", [])
+            u.setdefault("js_contrast", "")
+            u.setdefault("production_relevance", "")
+        units = [TeachingUnit(**u) for u in raw_units]
+    else:
+        units = [
+            TeachingUnit(
+                unit=i,
+                concept=f.stem.replace("_", " ").title(),
+                source_sections=[],
+                complexity=2,
+                word_budget=400,
+                key_facts=[],
+                common_misconception="",
+                good_analogy="",
+                question_style="recall",
+                memory_hook="",
+            )
+            for i, f in enumerate(unit_files)
+        ]
+
+    chunks_path = units_dir.parent / "tutorial.chunks.json"
+    if chunks_path.exists():
+        with open(chunks_path, encoding="utf-8") as f:
+            raw_chunks = json.load(f)
+        chunks = [Chunk(**c) for c in raw_chunks]
+    else:
+        chunks = []
+        _log.warning("tutorial.chunks.json not found — Q&A will work without source context")
+
+    no_qa = getattr(args, "no_qa", False)
+    provider = getattr(args, "provider", "groq")
+    if no_qa:
+        llm_fn = None
+    else:
+        try:
+            config = load_config()
+            llm_fn = _partial(_llm.chat, provider=provider, config=config)
+        except Exception:
+            llm_fn = None
+            _log.warning("Could not load config for Q&A — Q&A will be unavailable")
+
+    session = SessionLog(
+        source_file=str(getattr(args, "audio_file", getattr(args, "output", "unknown"))),
+        session_start=datetime.utcnow().isoformat(),
+        format="tutor-student",
+        duration_minutes=20,
+    )
+
+    return TutorPlayer(
+        unit_files=[str(f) for f in unit_files],
+        units=units,
+        chunks=chunks,
+        session=session,
+        llm_fn=llm_fn,
+        no_qa=no_qa,
+    )
+
+
+def _make_generate_parser() -> argparse.ArgumentParser:
+    """Return an ArgumentParser for the /generate shell command."""
+    parser = argparse.ArgumentParser(prog="generate", add_help=False)
+    parser.add_argument("input", nargs="?")
+    parser.add_argument("--output", default="tutorial.mp3")
+    parser.add_argument("--provider", default="groq")
+    parser.add_argument("--duration", type=int, default=DEFAULT_DURATION_MIN)
+    parser.add_argument("--format", default=DEFAULT_FORMAT, dest="fmt")
+    parser.add_argument("--difficulty", default=DEFAULT_DIFFICULTY)
+    parser.add_argument("--units", type=int, default=None)
+    parser.add_argument("--subject", default=DEFAULT_SUBJECT)
+    parser.add_argument("--topic", default=None)
+    parser.add_argument("--script-only", action="store_true", dest="script_only")
+    parser.add_argument("--dry-run", action="store_true", dest="dry_run")
+    parser.add_argument("--inspect", action="store_true")
+    parser.add_argument("--show-summaries", action="store_true", dest="show_summaries")
+    parser.add_argument("--no-cache", action="store_true", dest="no_cache")
+    parser.add_argument("--verbose", action="store_true")
+    parser.add_argument("--debug", action="store_true")
+    mode_group = parser.add_mutually_exclusive_group()
+    mode_group.add_argument("--explain", action="store_true")
+    mode_group.add_argument("--conversation", action="store_true")
+    return parser
+
+
+def _mode(args: argparse.Namespace) -> str:
+    if getattr(args, "inspect", False):
+        return "inspect"
+    if getattr(args, "dry_run", False):
+        return "dry-run"
+    if getattr(args, "script_only", False):
+        return "script-only"
+    return "generate"
+
+
+def _print_duration_estimate(script: list[DialogueLine]) -> None:
+    total_words = sum(len(line.text.split()) for line in script)
+    dialogue_secs = (total_words / WPM) * 60
+    silence_secs = 80
+    total_secs = int(dialogue_secs + silence_secs)
+    mins, secs = divmod(total_secs, 60)
+    print("\n=== Duration Estimate ===")
+    print(f"Script words:  {total_words:,}")
+    print(f"Estimated:     ~{mins}m {secs:02d}s (incl. pauses)")
+
+
+def _setup_logging(args: argparse.Namespace) -> None:
+    if getattr(args, "debug", False):
+        level = logging.DEBUG
+        logging.basicConfig(
+            level=level,
+            filename="tutor.log",
+            format="%(asctime)s %(name)s %(levelname)s %(message)s",
+        )
+    elif getattr(args, "verbose", False):
+        level = logging.INFO
+        logging.basicConfig(level=level, format="%(levelname)s %(message)s")
+    else:
+        logging.basicConfig(level=logging.WARNING, format="%(levelname)s %(message)s")
+
+
+if __name__ == "__main__":
+    main()