learnx-cli 0.3.0__py3-none-any.whl

tutor/tests/generation/test_narrator.py

@@ -0,0 +1,165 @@
+"""Tests for tutor/generation/narrator.py."""
+
+from unittest.mock import MagicMock, patch
+
+from tutor.generation.narrator import (
+    NARRATE_VERSION,
+    _chunk_to_unit,
+    _parse_narration,
+    narrate_all,
+)
+from tutor.models import Chunk
+
+
+def _make_chunk(
+    chunk_id: str = "sec_001",
+    heading: str = "What is Inheritance?",
+    text: str = "Inheritance lets one class extend another.",
+) -> Chunk:
+    return Chunk(
+        chunk_id=chunk_id,
+        breadcrumb=heading,
+        heading=heading,
+        level=2,
+        token_count=len(text.split()),
+        text=text,
+        has_code=False,
+    )
+
+
+# ── _parse_narration ──────────────────────────────────────────────────────────
+
+
+def test_parse_narration_extracts_alex_lines():
+    raw = "ALEX: This section covers inheritance.\nALEX: Use extends to create a subclass."
+    lines = _parse_narration(raw, unit_number=1)
+    assert len(lines) == 2
+    assert all(ln.speaker == "ALEX" for ln in lines)
+    assert lines[0].text == "This section covers inheritance."
+
+
+def test_parse_narration_skips_non_alex_lines():
+    raw = "ALEX: Hello.\nSome random text.\nMAYA: Should be ignored.\nALEX: End."
+    lines = _parse_narration(raw, unit_number=1)
+    assert len(lines) == 2
+    assert lines[1].text == "End."
+
+
+def test_parse_narration_sets_unit_number():
+    raw = "ALEX: Content here."
+    lines = _parse_narration(raw, unit_number=3)
+    assert lines[0].unit_number == 3
+
+
+def test_parse_narration_empty_input_returns_empty():
+    assert _parse_narration("", unit_number=1) == []
+
+
+def test_parse_narration_handles_dash_separator():
+    raw = "ALEX - This also works."
+    lines = _parse_narration(raw, unit_number=1)
+    assert len(lines) == 1
+    assert lines[0].text == "This also works."
+
+
+# ── _chunk_to_unit ────────────────────────────────────────────────────────────
+
+
+def test_chunk_to_unit_concept_is_heading():
+    chunk = _make_chunk(heading="The extends Keyword")
+    unit = _chunk_to_unit(chunk, unit_index=2)
+    assert unit.concept == "The extends Keyword"
+
+
+def test_chunk_to_unit_source_sections_contains_chunk_id():
+    chunk = _make_chunk(chunk_id="sec_003")
+    unit = _chunk_to_unit(chunk, unit_index=3)
+    assert "sec_003" in unit.source_sections
+
+
+def test_chunk_to_unit_complexity_is_one():
+    chunk = _make_chunk()
+    unit = _chunk_to_unit(chunk, unit_index=1)
+    assert unit.complexity == 1
+
+
+def test_chunk_to_unit_word_budget_proportional_to_source():
+    long_text = " ".join(["word"] * 200)
+    chunk = _make_chunk(text=long_text)
+    unit = _chunk_to_unit(chunk, unit_index=1)
+    assert unit.word_budget >= 200
+
+
+def test_chunk_to_unit_falls_back_to_section_number_when_no_heading():
+    chunk = _make_chunk(heading="")
+    unit = _chunk_to_unit(chunk, unit_index=5)
+    assert "5" in unit.concept
+
+
+# ── narrate_all ───────────────────────────────────────────────────────────────
+
+
+def _fake_llm(response: str) -> MagicMock:
+    mock = MagicMock(return_value=response)
+    return mock
+
+
+def test_narrate_all_returns_one_unit_per_chunk(tmp_path):
+    chunks = [_make_chunk(chunk_id=f"sec_{i:03d}", heading=f"Section {i}") for i in range(3)]
+    llm_fn = _fake_llm("ALEX: This section explains the concept.\nALEX: Here is a detail.")
+
+    with patch("tutor.generation.narrator.SUMMARY_CACHE_DIR", str(tmp_path)):
+        units, all_lines = narrate_all(chunks, "Inheritance", llm_fn, cache_dir=str(tmp_path))
+
+    assert len(units) == 3
+    assert len(all_lines) == 3
+
+
+def test_narrate_all_units_only_have_alex_lines(tmp_path):
+    chunks = [_make_chunk()]
+    llm_fn = _fake_llm("ALEX: Only ALEX speaks.\nALEX: And again.")
+
+    with patch("tutor.generation.narrator.SUMMARY_CACHE_DIR", str(tmp_path)):
+        _, all_lines = narrate_all(chunks, "Doc", llm_fn, cache_dir=str(tmp_path))
+
+    for lines in all_lines:
+        assert all(ln.speaker == "ALEX" for ln in lines)
+
+
+def test_narrate_all_uses_cache_on_second_call(tmp_path):
+    chunks = [_make_chunk()]
+    llm_fn = _fake_llm("ALEX: First call.")
+
+    with patch("tutor.generation.narrator.SUMMARY_CACHE_DIR", str(tmp_path)):
+        narrate_all(chunks, "Doc", llm_fn, cache_dir=str(tmp_path))
+        narrate_all(chunks, "Doc", llm_fn, cache_dir=str(tmp_path))
+
+    assert llm_fn.call_count == 1
+
+
+def test_narrate_all_cache_files_use_narrate_suffix(tmp_path):
+    chunks = [_make_chunk()]
+    llm_fn = _fake_llm("ALEX: Cached content.")
+
+    with patch("tutor.generation.narrator.SUMMARY_CACHE_DIR", str(tmp_path)):
+        narrate_all(chunks, "Doc", llm_fn, cache_dir=str(tmp_path))
+
+    cache_files = list(tmp_path.glob("*.narrate.json"))
+    assert len(cache_files) == 1
+
+
+def test_narrate_all_does_not_share_cache_with_dialogue(tmp_path):
+    """Narrate cache keys must differ from dialogue cache keys for same chunk."""
+    import hashlib
+
+    chunk = _make_chunk()
+    narrate_key = hashlib.md5((chunk.chunk_id + chunk.text + NARRATE_VERSION).encode()).hexdigest()
+
+    # Simulate a dialogue cache file with the same chunk content
+    from tutor.constants import PROMPT_VERSION
+
+    dialogue_key = hashlib.md5(
+        (chunk.heading + str(400) + "tutor-student" + "beginner" + PROMPT_VERSION).encode()
+    ).hexdigest()
+
+    assert narrate_key != dialogue_key

tutor/tests/generation/test_segment_edge_cases.py

@@ -0,0 +1,280 @@
+"""Tests for edge cases: fallback, gap filling, invalid LLM responses, field validation."""
+
+from __future__ import annotations
+
+import json
+
+from tutor.generation.segment_planner import plan_segments
+
+from .conftest import (
+    _make_unit_entry,
+    _units_json,
+)
+
+# ---------------------------------------------------------------------------
+# Fallback on bad LLM response
+# ---------------------------------------------------------------------------
+
+
+def test_invalid_json_from_llm_returns_fallback(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+
+    def bad_llm(messages, call_type="segments"):
+        return "this is not JSON at all !!!"
+
+    result = plan_segments(units_json, tmp_path / "video", bad_llm)
+    segs = result[1]
+    assert len(segs) >= 1
+    assert segs[0].visual_type == "hook_question"
+    assert segs[-1].visual_type == "memory_hook"
+
+
+def test_llm_exception_returns_fallback(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+
+    def exploding_llm(messages, call_type="segments"):
+        raise RuntimeError("network failure")
+
+    result = plan_segments(units_json, tmp_path / "video", exploding_llm)
+    segs = result[1]
+    assert len(segs) >= 1
+    assert segs[0].visual_type == "hook_question"
+
+
+# ---------------------------------------------------------------------------
+# Field validation
+# ---------------------------------------------------------------------------
+
+
+def test_unknown_visual_type_replaced_with_key_insight(tmp_path):
+    def banana_llm(messages, call_type="segments"):
+        return json.dumps(
+            [
+                {
+                    "lines_start": 0,
+                    "lines_end": 0,
+                    "visual_type": "hook_question",
+                    "title": "Open",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+                {
+                    "lines_start": 1,
+                    "lines_end": 2,
+                    "visual_type": "banana",
+                    "title": "Unknown",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+                {
+                    "lines_start": 3,
+                    "lines_end": 3,
+                    "visual_type": "memory_hook",
+                    "title": "Remember",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+            ]
+        )
+
+    units = [_make_unit_entry(1, n_lines=4)]
+    units_json = _units_json(tmp_path, units)
+    result = plan_segments(units_json, tmp_path / "video", banana_llm)
+    types = [s.visual_type for s in result[1]]
+    assert "banana" not in types
+    assert "key_insight" in types
+
+
+def test_out_of_bounds_indices_clamped(tmp_path):
+    n = 5
+
+    def oob_llm(messages, call_type="segments"):
+        return json.dumps(
+            [
+                {
+                    "lines_start": 0,
+                    "lines_end": 0,
+                    "visual_type": "hook_question",
+                    "title": "Open",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+                {
+                    "lines_start": 1,
+                    "lines_end": 999,
+                    "visual_type": "key_insight",
+                    "title": "Key",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+            ]
+        )
+
+    units = [_make_unit_entry(1, n_lines=n)]
+    units_json = _units_json(tmp_path, units)
+    result = plan_segments(units_json, tmp_path / "video", oob_llm)
+    for seg in result[1]:
+        assert seg.lines_end <= n - 1
+        assert seg.lines_start >= 0
+
+
+def test_mermaid_null_for_non_diagram_types(tmp_path):
+    def mermaid_llm(messages, call_type="segments"):
+        return json.dumps(
+            [
+                {
+                    "lines_start": 0,
+                    "lines_end": 0,
+                    "visual_type": "hook_question",
+                    "title": "Open",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": "classDiagram\n  A --> B",
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+                {
+                    "lines_start": 1,
+                    "lines_end": 2,
+                    "visual_type": "key_insight",
+                    "title": "Key",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": "classDiagram\n  A --> B",
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+                {
+                    "lines_start": 3,
+                    "lines_end": 3,
+                    "visual_type": "memory_hook",
+                    "title": "Rem",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+            ]
+        )
+
+    units = [_make_unit_entry(1, n_lines=4)]
+    units_json = _units_json(tmp_path, units)
+    result = plan_segments(units_json, tmp_path / "video", mermaid_llm)
+    for seg in result[1]:
+        if seg.visual_type != "diagram":
+            assert seg.mermaid is None
+
+
+# ---------------------------------------------------------------------------
+# Gap filling
+# ---------------------------------------------------------------------------
+
+
+def test_gap_filled_with_key_insight(tmp_path):
+    n = 8
+
+    def gap_llm(messages, call_type="segments"):
+        return json.dumps(
+            [
+                {
+                    "lines_start": 0,
+                    "lines_end": 0,
+                    "visual_type": "hook_question",
+                    "title": "Open",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+                {
+                    "lines_start": 1,
+                    "lines_end": 2,
+                    "visual_type": "key_insight",
+                    "title": "Key",
+                    "body": None,
+                    "code": None,
+                    "language": None,
+                    "mermaid": None,
+                    "left": None,
+                    "right": None,
+                    "rows": None,
+                },
+            ]
+        )
+
+    units = [_make_unit_entry(1, n_lines=n)]
+    units_json = _units_json(tmp_path, units)
+    result = plan_segments(units_json, tmp_path / "video", gap_llm)
+    segs = result[1]
+    covered = set()
+    for seg in segs:
+        covered.update(range(seg.lines_start, seg.lines_end + 1))
+    assert covered == set(range(n))
+    gap_segs = [s for s in segs if s.lines_start >= 3]
+    assert any(s.visual_type == "key_insight" for s in gap_segs)
+
+
+def test_single_line_unit_fallback_has_two_segments(tmp_path):
+    units = [_make_unit_entry(1, n_lines=1)]
+    units_json = _units_json(tmp_path, units)
+
+    def bad_llm(messages, call_type="segments"):
+        return "not json"
+
+    result = plan_segments(units_json, tmp_path / "video", bad_llm)
+    segs = result[1]
+    assert len(segs) == 2
+    assert segs[0].visual_type == "hook_question"
+    assert segs[1].visual_type == "memory_hook"
+
+
+def test_two_line_unit_fallback_covers_both(tmp_path):
+    units = [_make_unit_entry(1, n_lines=2)]
+    units_json = _units_json(tmp_path, units)
+
+    def bad_llm(messages, call_type="segments"):
+        return "not json"
+
+    result = plan_segments(units_json, tmp_path / "video", bad_llm)
+    segs = result[1]
+    covered = set()
+    for seg in segs:
+        covered.update(range(seg.lines_start, seg.lines_end + 1))
+    assert covered == {0, 1}