learnx-cli 0.3.0__py3-none-any.whl

tutor/tests/e2e/fixtures/sample.md

@@ -0,0 +1,13 @@
+# What is a Variable?
+
+A variable is a named container that holds a value in a computer program.
+Think of it like a labeled box: you put something inside the box, give the
+box a name, and later you can find what you stored by using that name.
+
+For example, in Python you might write `age = 25`. This creates a variable
+called `age` and stores the number 25 in it. Later, when your program needs
+to know the age, it looks inside the `age` box and finds 25.
+
+Variables can hold different types of data: numbers, text, lists, or more
+complex structures. The type determines what operations you can perform on
+the value — you can add two numbers, but you cannot add a number to a sentence.

tutor/tests/e2e/test_audio_quality.py

@@ -0,0 +1,40 @@
+"""Audio quality: not silent, duration reasonable, correct sample rate."""
+
+from pydub import AudioSegment
+
+
+def test_audio_not_silent(pipeline_output):
+    """Assert tutorial.mp3 is not silent (dBFS > -60)."""
+    mp3 = pipeline_output / "tutorial.mp3"
+    audio = AudioSegment.from_mp3(str(mp3))
+    assert audio.dBFS > -60, (
+        f"tutorial.mp3 appears silent: dBFS={audio.dBFS:.1f} (threshold: -60 dBFS)"
+    )
+
+
+def test_audio_duration_positive(pipeline_output):
+    """Assert tutorial.mp3 has a positive duration in milliseconds."""
+    mp3 = pipeline_output / "tutorial.mp3"
+    audio = AudioSegment.from_mp3(str(mp3))
+    assert len(audio) > 0, "tutorial.mp3 has zero duration"
+
+
+def test_audio_duration_matches_fixture_length(pipeline_output):
+    """Assert tutorial.mp3 is at least 10 seconds long for a 3-paragraph fixture."""
+    mp3 = pipeline_output / "tutorial.mp3"
+    audio = AudioSegment.from_mp3(str(mp3))
+    assert len(audio) > 10_000, (
+        f"tutorial.mp3 too short: {len(audio)}ms (expected > 10000ms for a 3-paragraph fixture)"
+    )
+
+
+def test_unit_audio_not_silent(pipeline_output):
+    """Assert each unit_*.mp3 is not silent (dBFS > -60)."""
+    units_dir = pipeline_output / "tutorial_units"
+    unit_files = sorted(units_dir.glob("unit_*.mp3"))
+    assert unit_files, f"No unit_*.mp3 found in {units_dir}"
+    for unit_path in unit_files:
+        audio = AudioSegment.from_mp3(str(unit_path))
+        assert audio.dBFS > -60, (
+            f"{unit_path.name} appears silent: dBFS={audio.dBFS:.1f} (threshold: -60 dBFS)"
+        )

tutor/tests/e2e/test_av_sync.py

@@ -0,0 +1,56 @@
+"""A/V sync: timing.json per-unit end_ms vs unit MP3 duration drift < 500ms."""
+
+import json
+
+import pytest
+from pydub import AudioSegment
+
+from tutor.constants import SILENCE_BREATH_MS, SILENCE_TURN_MS
+
+
+def test_timing_units_nonempty(pipeline_output):
+    """Assert timing.json contains at least one unit entry."""
+    timing_path = pipeline_output / "tutorial.timing.json"
+    timing = json.loads(timing_path.read_text(encoding="utf-8"))
+    assert timing["units"], "timing.json 'units' dict is empty — no timing data captured"
+
+
+def test_timing_end_matches_audio_duration(pipeline_output):
+    """Assert per-unit last end_ms vs unit MP3 duration drift is under 500ms."""
+    timing_path = pipeline_output / "tutorial.timing.json"
+    timing = json.loads(timing_path.read_text(encoding="utf-8"))
+    units_dir = pipeline_output / "tutorial_units"
+
+    for unit_key, entries in timing["units"].items():
+        if not entries:
+            continue
+        last_end_ms = entries[-1]["end_ms"]
+        unit_num = int(unit_key)
+        unit_mp3 = units_dir / f"unit_{unit_num:02d}.mp3"
+
+        if not unit_mp3.exists():
+            pytest.skip(f"Unit MP3 not found: {unit_mp3}")
+
+        audio_duration_ms = len(AudioSegment.from_mp3(str(unit_mp3)))
+        drift = abs(last_end_ms - audio_duration_ms)
+        assert drift < 500, (
+            f"Unit {unit_key}: timing end_ms={last_end_ms}ms vs "
+            f"audio duration={audio_duration_ms}ms (drift={drift}ms, threshold=500ms)"
+        )
+
+
+def test_no_timing_gaps(pipeline_output):
+    """Assert consecutive timing entries have only BREATH or TURN silence gaps."""
+    timing_path = pipeline_output / "tutorial.timing.json"
+    timing = json.loads(timing_path.read_text(encoding="utf-8"))
+
+    for unit_key, entries in timing["units"].items():
+        for i in range(1, len(entries)):
+            prev_speaker = entries[i - 1]["speaker"]
+            curr_speaker = entries[i]["speaker"]
+            gap = entries[i]["start_ms"] - entries[i - 1]["end_ms"]
+            expected = SILENCE_BREATH_MS if prev_speaker == curr_speaker else SILENCE_TURN_MS
+            assert gap == expected, (
+                f"Unit {unit_key}, entry {i}: gap={gap}ms, "
+                f"expected {expected}ms ({prev_speaker}→{curr_speaker})"
+            )

tutor/tests/e2e/test_pipeline_smoke.py

@@ -0,0 +1,37 @@
+"""Smoke test: full pipeline runs without crash and produces expected output files."""
+
+import json
+
+
+def test_pipeline_exits_zero(pipeline_output):
+    """Assert the pipeline ran successfully and created the output directory."""
+    assert pipeline_output.exists(), f"Output directory not created: {pipeline_output}"
+
+
+def test_mp3_exists_and_nonempty(pipeline_output):
+    """Assert tutorial.mp3 exists and has non-zero size."""
+    mp3 = pipeline_output / "tutorial.mp3"
+    assert mp3.exists(), f"tutorial.mp3 not found in {pipeline_output}"
+    assert mp3.stat().st_size > 0, "tutorial.mp3 is empty"
+
+
+def test_timing_json_exists(pipeline_output):
+    """Assert tutorial.timing.json was written to the output directory."""
+    timing = pipeline_output / "tutorial.timing.json"
+    assert timing.exists(), f"tutorial.timing.json not found in {pipeline_output}"
+
+
+def test_timing_json_is_valid(pipeline_output):
+    """Assert tutorial.timing.json is valid JSON with 'version' and 'units' keys."""
+    timing_path = pipeline_output / "tutorial.timing.json"
+    data = json.loads(timing_path.read_text(encoding="utf-8"))
+    assert "version" in data, "timing.json missing 'version' key"
+    assert "units" in data, "timing.json missing 'units' key"
+
+
+def test_unit_mp3s_exist(pipeline_output):
+    """Assert at least one unit_*.mp3 file exists in tutorial_units/."""
+    units_dir = pipeline_output / "tutorial_units"
+    assert units_dir.exists(), f"tutorial_units/ directory not found in {pipeline_output}"
+    unit_files = list(units_dir.glob("unit_*.mp3"))
+    assert len(unit_files) >= 1, f"No unit_*.mp3 files found in {units_dir}"

tutor/tests/e2e/test_slide_render.py

@@ -0,0 +1,72 @@
+"""Slide render: Playwright loads HTML slides, page is not blank, no error messages."""
+
+import pathlib
+import tempfile
+
+import pytest
+
+SLIDE_DIR = pathlib.Path(tempfile.gettempdir()) / "learnx_e2e_smoke" / "slides"
+SCREENSHOT_PATH = pathlib.Path(tempfile.gettempdir()) / "learnx_e2e_smoke" / "slide_01.png"
+
+
+def _first_slide():
+    """Return the first HTML slide path; fail clearly if slides/ is empty."""
+    html_files = sorted(SLIDE_DIR.glob("*.html"))
+    assert html_files, f"No .html files found in {SLIDE_DIR}"
+    return html_files[0]
+
+
+@pytest.fixture(scope="module")
+def browser_page(pipeline_output):
+    """Launch a Playwright Chromium browser and yield a reusable page object."""
+    if not SLIDE_DIR.exists():
+        pytest.skip("slides/ directory not present — visual pipeline not run")
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page(viewport={"width": 1280, "height": 720})
+        yield page
+        browser.close()
+
+
+def test_at_least_one_slide_exists(pipeline_output):
+    """Assert the slides/ directory contains at least one .html file."""
+    if not SLIDE_DIR.exists():
+        pytest.skip("slides/ directory not present — visual pipeline not run")
+    html_files = list(SLIDE_DIR.glob("*.html"))
+    assert html_files, f"No .html files found in {SLIDE_DIR}"
+
+
+def test_slide_page_not_blank(browser_page):
+    """Assert the first slide's page content exceeds 500 characters."""
+    browser_page.goto(_first_slide().as_uri())
+    content = browser_page.content()
+    assert len(content) > 500, (
+        f"Slide page appears blank: content length={len(content)} (expected > 500)"
+    )
+
+
+def test_slide_has_visible_text(browser_page):
+    """Assert the first slide has non-empty visible body text."""
+    browser_page.goto(_first_slide().as_uri())
+    text = browser_page.locator("body").inner_text().strip()
+    assert text, "Slide body contains no visible text"
+
+
+def test_slide_no_error_messages(browser_page):
+    """Assert no 'Error' or 'TypeError' text appears in the slide body."""
+    browser_page.goto(_first_slide().as_uri())
+    text = browser_page.locator("body").inner_text()
+    assert "Error" not in text, "Slide contains 'Error' in visible text"
+    assert "TypeError" not in text, "Slide contains 'TypeError' in visible text"
+
+
+def test_slide_screenshot_saved(browser_page):
+    """Assert a non-blank screenshot can be taken and saved from the first slide."""
+    browser_page.goto(_first_slide().as_uri())
+    browser_page.screenshot(path=str(SCREENSHOT_PATH))
+    assert SCREENSHOT_PATH.exists(), f"Screenshot not saved: {SCREENSHOT_PATH}"
+    assert SCREENSHOT_PATH.stat().st_size > 5000, (
+        f"Screenshot too small ({SCREENSHOT_PATH.stat().st_size} bytes) — may be a blank image"
+    )

tutor/tests/e2e/test_video_streams.py

@@ -0,0 +1,104 @@
+"""Video stream verification: audio and video streams both present, durations non-zero."""
+
+import json
+import subprocess
+
+import pytest
+
+
+def _to_float(value, default: float = 0.0) -> float:
+    """Return float(value) or default when value is non-numeric (e.g. 'N/A')."""
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _to_int(value, default: int = 0) -> int:
+    """Return int(value) or default when value is non-numeric (e.g. 'N/A')."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def ffprobe_streams(path):
+    """Run ffprobe on path and return the list of stream dicts."""
+    result = subprocess.run(
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-show_entries",
+            "stream=codec_type,duration,bit_rate",
+            "-of",
+            "json",
+            str(path),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        pytest.fail(f"ffprobe failed (rc={result.returncode}): {result.stderr.strip()}")
+    return json.loads(result.stdout)["streams"]
+
+
+def _get_mp4(pipeline_output):
+    """Return the expected tutorial.mp4 path inside pipeline_output."""
+    return pipeline_output / "tutorial.mp4"
+
+
+def test_video_file_exists(pipeline_output):
+    """Assert tutorial.mp4 exists and has non-zero size; skip if absent."""
+    mp4 = _get_mp4(pipeline_output)
+    if not mp4.exists():
+        pytest.skip("tutorial.mp4 not present — video pipeline not run")
+    assert mp4.stat().st_size > 0, "tutorial.mp4 is empty"
+
+
+def test_video_stream_present(pipeline_output):
+    """Assert tutorial.mp4 contains at least one video stream."""
+    mp4 = _get_mp4(pipeline_output)
+    if not mp4.exists():
+        pytest.skip("tutorial.mp4 not present — video pipeline not run")
+    streams = ffprobe_streams(mp4)
+    codec_types = [s.get("codec_type") for s in streams]
+    assert "video" in codec_types, f"No video stream found in tutorial.mp4; streams: {codec_types}"
+
+
+def test_audio_stream_present(pipeline_output):
+    """Assert tutorial.mp4 contains an audio stream — catches the silent-video bug."""
+    mp4 = _get_mp4(pipeline_output)
+    if not mp4.exists():
+        pytest.skip("tutorial.mp4 not present — video pipeline not run")
+    streams = ffprobe_streams(mp4)
+    codec_types = [s.get("codec_type") for s in streams]
+    assert "audio" in codec_types, (
+        f"No audio stream found in tutorial.mp4 — this is the silent-video bug; "
+        f"streams: {codec_types}"
+    )
+
+
+def test_audio_stream_duration_nonzero(pipeline_output):
+    """Assert the audio stream duration is greater than zero."""
+    mp4 = _get_mp4(pipeline_output)
+    if not mp4.exists():
+        pytest.skip("tutorial.mp4 not present — video pipeline not run")
+    streams = ffprobe_streams(mp4)
+    audio_streams = [s for s in streams if s.get("codec_type") == "audio"]
+    assert audio_streams, "No audio stream found"
+    duration = _to_float(audio_streams[0].get("duration"))
+    assert duration > 0, f"Audio stream has zero duration: {duration}"
+
+
+def test_audio_stream_not_muted(pipeline_output):
+    """Assert audio stream bitrate is non-zero, ruling out a muted stream."""
+    mp4 = _get_mp4(pipeline_output)
+    if not mp4.exists():
+        pytest.skip("tutorial.mp4 not present — video pipeline not run")
+    streams = ffprobe_streams(mp4)
+    audio_streams = [s for s in streams if s.get("codec_type") == "audio"]
+    assert audio_streams, "No audio stream found"
+    bit_rate = _to_int(audio_streams[0].get("bit_rate"))
+    assert bit_rate > 0, f"Audio stream bitrate is zero — stream may be silent: {bit_rate}"

tutor/tests/generation/conftest.py

@@ -0,0 +1,134 @@
+"""Shared fixtures and helpers for segment planner tests."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from tutor.models import DialogueLine
+
+N_LINES = 6
+
+
+def _line(i: int, speaker: str = "ALEX", unit: int = 1) -> DialogueLine:
+    return DialogueLine(speaker=speaker, text=f"Line {i}", unit_number=unit)
+
+
+def _make_lines(n: int = N_LINES, unit: int = 1) -> list[DialogueLine]:
+    speakers = ["ALEX", "MAYA", "ALEX", "MAYA", "ALEX", "ALEX"]
+    return [_line(i, speakers[i % len(speakers)], unit) for i in range(n)]
+
+
+def _make_unit_entry(
+    unit_num: int = 1, concept: str = "Test Concept", n_lines: int = N_LINES
+) -> dict:
+    lines = [
+        {"speaker": "ALEX" if i % 2 == 0 else "MAYA", "text": f"Line {i}", "unit_number": unit_num}
+        for i in range(n_lines)
+    ]
+    return {
+        "unit": unit_num,
+        "concept": concept,
+        "lines": lines,
+        "source_sections": [],
+        "complexity": 1,
+        "word_budget": 200,
+        "key_facts": [],
+        "common_misconception": "",
+        "good_analogy": "",
+        "question_style": "",
+        "memory_hook": "",
+    }
+
+
+def _units_json(tmp_path: Path, units: list[dict]) -> Path:
+    p = tmp_path / "tutorial.units.json"
+    p.write_text(json.dumps(units), encoding="utf-8")
+    return p
+
+
+def _valid_response(lines: list[DialogueLine]) -> str:
+    n = len(lines)
+    mid_end = max(1, n - 2)
+    return json.dumps(
+        [
+            {
+                "lines_start": 0,
+                "lines_end": 0,
+                "visual_type": "hook_question",
+                "title": "Opening",
+                "body": None,
+                "code": None,
+                "language": None,
+                "mermaid": None,
+                "left": None,
+                "right": None,
+                "rows": None,
+            },
+            {
+                "lines_start": 1,
+                "lines_end": mid_end,
+                "visual_type": "key_insight",
+                "title": "Key Point",
+                "body": None,
+                "code": None,
+                "language": None,
+                "mermaid": None,
+                "left": None,
+                "right": None,
+                "rows": None,
+            },
+            {
+                "lines_start": mid_end + 1,
+                "lines_end": n - 1,
+                "visual_type": "memory_hook",
+                "title": "Remember",
+                "body": None,
+                "code": None,
+                "language": None,
+                "mermaid": None,
+                "left": None,
+                "right": None,
+                "rows": None,
+            },
+        ]
+    )
+
+
+def _fake_llm(lines: list[DialogueLine]):
+    def _llm(messages, call_type="segments"):
+        return _valid_response(lines)
+
+    return _llm
+
+
+# ---------------------------------------------------------------------------
+# pytest fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def make_lines():
+    return _make_lines
+
+
+@pytest.fixture()
+def make_unit_entry():
+    return _make_unit_entry
+
+
+@pytest.fixture()
+def units_json_factory():
+    return _units_json
+
+
+@pytest.fixture()
+def fake_llm_factory():
+    return _fake_llm
+
+
+@pytest.fixture()
+def valid_response_factory():
+    return _valid_response

tutor/tests/generation/test_assembler.py

@@ -0,0 +1,64 @@
+from tutor.generation.assembler import assemble
+from tutor.models import DialogueLine, TeachingUnit
+
+
+def _make_unit(n: int) -> TeachingUnit:
+    return TeachingUnit(
+        unit=n,
+        concept=f"Concept {n}",
+        source_sections=[f"s0{n}"],
+        complexity=2,
+        word_budget=400,
+        key_facts=["fact"],
+        common_misconception="wrong belief",
+        good_analogy="like a thing",
+        question_style="recall",
+        memory_hook=f"Remember concept {n}",
+    )
+
+
+def _make_lines(unit_num: int, count: int = 4) -> list[DialogueLine]:
+    return [
+        DialogueLine(
+            speaker="ALEX" if i % 2 == 0 else "MAYA",
+            text=f"Unit {unit_num} line {i}",
+            unit_number=unit_num,
+        )
+        for i in range(count)
+    ]
+
+
+def test_assemble_starts_with_alex_intro():
+    units = [_make_unit(1), _make_unit(2)]
+    result = assemble(units, [_make_lines(1), _make_lines(2)], "tutor-student", "Java Basics")
+    assert result[0].speaker == "ALEX"
+    assert result[0].unit_number == 0
+
+
+def test_assemble_ends_with_outro():
+    units = [_make_unit(1)]
+    result = assemble(units, [_make_lines(1)], "tutor-student", "Java Basics")
+    assert result[-1].unit_number == -1
+
+
+def test_assemble_transitions_between_units():
+    units = [_make_unit(1), _make_unit(2)]
+    result = assemble(units, [_make_lines(1), _make_lines(2)], "tutor-student", "Java Basics")
+    unit_numbers = [ln.unit_number for ln in result]
+    assert 1 in unit_numbers and 2 in unit_numbers
+
+
+def test_assemble_outro_contains_memory_hooks():
+    units = [_make_unit(1), _make_unit(2)]
+    result = assemble(units, [_make_lines(1), _make_lines(2)], "tutor-student", "Java Basics")
+    outro = result[-1]
+    assert "Remember concept 1" in outro.text
+    assert "Remember concept 2" in outro.text
+
+
+def test_sanitizer_applied_no_symbols():
+    units = [_make_unit(1)]
+    lines = [DialogueLine(speaker="ALEX", text="Use List<String>", unit_number=1)]
+    result = assemble(units, [lines], "tutor-student", "Java Basics")
+    for line in result:
+        assert "<" not in line.text, f"Symbol leak in: {line.text}"

tutor/tests/generation/test_curriculum.py

@@ -0,0 +1,107 @@
+import json
+
+import pytest
+
+from tutor.generation.curriculum import plan
+from tutor.models import Chunk, DocProfile
+
+
+def _make_profile() -> DocProfile:
+    return DocProfile(
+        filepath="test.md",
+        raw_bytes=10_000,
+        estimated_tokens=5_000,
+        strategy="B",
+        section_count=5,
+        has_code_blocks=True,
+        language_hint="java",
+    )
+
+
+def _make_chunks() -> list[Chunk]:
+    return [
+        Chunk(
+            chunk_id=f"s0{i}",
+            breadcrumb=f"Section {i}",
+            heading=f"Section {i}",
+            level=2,
+            token_count=500,
+            text=f"Content about concept {i}. " * 50,
+            has_code=True,
+            summary=f"This section covers concept {i} with a practical example.",
+        )
+        for i in range(1, 5)
+    ]
+
+
+GOOD_RESPONSE = json.dumps(
+    [
+        {
+            "concept": "Pass-by-Value",
+            "source_sections": ["s01"],
+            "complexity": 3,
+            "key_facts": ["Java passes references by value"],
+            "common_misconception": "Thinks Java passes objects by reference",
+            "good_analogy": "Copying an address, not a house",
+            "question_style": "predict",
+            "memory_hook": "Copy the address, not the house",
+            "prerequisite_concepts": [],
+        },
+        {
+            "concept": "String Equality",
+            "source_sections": ["s02"],
+            "complexity": 2,
+            "key_facts": ["Use .equals() not =="],
+            "common_misconception": "Thinks == compares content",
+            "good_analogy": "Two identical keys from different locksmiths",
+            "question_style": "error-spot",
+            "memory_hook": "Reference check, not content check",
+            "prerequisite_concepts": [],
+        },
+    ]
+)
+
+
+def fake_llm(messages, call_type="dialogue"):
+    return GOOD_RESPONSE
+
+
+def test_plan_returns_teaching_units():
+    from tutor.models import TeachingUnit
+
+    units = plan(_make_chunks(), _make_profile(), 20, fake_llm)
+    assert len(units) == 2
+    assert all(isinstance(u, TeachingUnit) for u in units)
+
+
+def test_plan_computes_word_budgets():
+    units = plan(_make_chunks(), _make_profile(), 20, fake_llm)
+    for u in units:
+        assert u.word_budget > 0
+
+
+def test_plan_raises_on_empty_response():
+    from tutor.exceptions import LLMError
+
+    def empty_llm(messages, call_type="dialogue"):
+        return "[]"
+
+    with pytest.raises(LLMError):
+        plan(_make_chunks(), _make_profile(), 20, empty_llm)
+
+
+def test_plan_raises_on_bad_json():
+    from tutor.exceptions import LLMError
+
+    def bad_llm(messages, call_type="dialogue"):
+        return "not json at all"
+
+    with pytest.raises(LLMError):
+        plan(_make_chunks(), _make_profile(), 20, bad_llm)
+
+
+def test_word_budget_proportional_to_complexity():
+    units = plan(_make_chunks(), _make_profile(), 20, fake_llm)
+    # Unit 0 has complexity 3, Unit 1 has complexity 2 → ratio should be 3:2 = 1.5
+    ratio = units[0].word_budget / units[1].word_budget
+    assert 1.4 <= ratio <= 1.6