learnx-cli 0.3.0__py3-none-any.whl

tutor/tests/generation/test_segment_planner.py

@@ -0,0 +1,324 @@
+"""Tests for plan_segments() public API (output shape, JSON output, caching)."""
+
+from __future__ import annotations
+
+import json
+
+from tutor.generation.segment_planner import plan_segments
+
+from .conftest import (
+    N_LINES,
+    _fake_llm,
+    _make_lines,
+    _make_unit_entry,
+    _units_json,
+    _valid_response,
+)
+
+# ---------------------------------------------------------------------------
+# Output shape
+# ---------------------------------------------------------------------------
+
+
+def test_plan_segments_returns_dict_keyed_by_unit(tmp_path):
+    units = [_make_unit_entry(1), _make_unit_entry(2)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    assert isinstance(result, dict)
+    assert 1 in result
+    assert 2 in result
+    assert all(isinstance(k, int) for k in result)
+
+
+def test_all_lines_covered(tmp_path):
+    n = N_LINES
+    units = [_make_unit_entry(1, n_lines=n)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines(n)
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    segs = result[1]
+    covered = set()
+    for seg in segs:
+        covered.update(range(seg.lines_start, seg.lines_end + 1))
+    assert covered == set(range(n))
+
+
+def test_no_line_covered_twice(tmp_path):
+    n = N_LINES
+    units = [_make_unit_entry(1, n_lines=n)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines(n)
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    segs = result[1]
+    covered = []
+    for seg in segs:
+        covered.extend(range(seg.lines_start, seg.lines_end + 1))
+    assert len(covered) == len(set(covered)), "Some lines covered twice"
+
+
+def test_first_segment_is_hook_question(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    assert result[1][0].visual_type == "hook_question"
+
+
+def test_last_segment_is_memory_hook(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    assert result[1][-1].visual_type == "memory_hook"
+
+
+def test_segment_index_is_sequential(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    indices = [s.segment_index for s in result[1]]
+    assert indices == list(range(len(indices)))
+
+
+def test_unit_with_zero_lines_skipped_not_crashed(tmp_path):
+    units = [_make_unit_entry(1, n_lines=0), _make_unit_entry(2, n_lines=N_LINES)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    result = plan_segments(units_json, tmp_path / "video", _fake_llm(lines))
+    assert 1 not in result
+    assert 2 in result
+
+
+# ---------------------------------------------------------------------------
+# JSON output file
+# ---------------------------------------------------------------------------
+
+
+def test_segments_json_written_to_video_dir(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    video_dir = tmp_path / "video"
+    plan_segments(units_json, video_dir, _fake_llm(lines))
+    assert (video_dir / "tutorial.segments.json").exists()
+
+
+def test_segments_json_has_version_1(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    video_dir = tmp_path / "video"
+    plan_segments(units_json, video_dir, _fake_llm(lines))
+    data = json.loads((video_dir / "tutorial.segments.json").read_text())
+    assert data["version"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Caching
+# ---------------------------------------------------------------------------
+
+
+def test_cache_hit_skips_llm_call(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    call_count = 0
+
+    def counting_llm(messages, call_type="segments"):
+        nonlocal call_count
+        call_count += 1
+        return _valid_response(lines)
+
+    video_dir = tmp_path / "video"
+    plan_segments(units_json, video_dir, counting_llm, no_cache=True)
+    assert call_count == 1
+
+    plan_segments(units_json, video_dir, counting_llm)
+    assert call_count == 1
+
+
+def test_no_cache_forces_regeneration(tmp_path):
+    units = [_make_unit_entry(1)]
+    units_json = _units_json(tmp_path, units)
+    lines = _make_lines()
+    call_count = 0
+
+    def counting_llm(messages, call_type="segments"):
+        nonlocal call_count
+        call_count += 1
+        return _valid_response(lines)
+
+    video_dir = tmp_path / "video"
+    plan_segments(units_json, video_dir, counting_llm, no_cache=True)
+    assert call_count == 1
+
+    plan_segments(units_json, video_dir, counting_llm, no_cache=True)
+    assert call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# Backward-compat: visual_planner API still callable
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# New types: step_sequence and callout
+# ---------------------------------------------------------------------------
+
+
+def test_step_sequence_in_valid_types():
+    from tutor.models import VALID_VISUAL_TYPES
+
+    assert "step_sequence" in VALID_VISUAL_TYPES
+
+
+def test_callout_in_valid_types():
+    from tutor.models import VALID_VISUAL_TYPES
+
+    assert "callout" in VALID_VISUAL_TYPES
+
+
+def test_step_sequence_fallback_on_empty_body(caplog):
+    """step_sequence with empty body is reclassified to definition."""
+    import logging
+
+    from tutor.generation.segment_parser import _validate_segment
+    from tutor.models import SlideSegment
+
+    seg = SlideSegment(
+        unit_index=1,
+        segment_index=0,
+        lines_start=0,
+        lines_end=1,
+        visual_type="step_sequence",
+        title="Steps to deploy",
+        body=None,
+        code=None,
+        language=None,
+        mermaid=None,
+        left=None,
+        right=None,
+        rows=None,
+    )
+    with caplog.at_level(logging.WARNING):
+        result = _validate_segment(seg)
+    assert result.visual_type == "definition"
+    assert "step_sequence" in caplog.text
+    assert "body is empty" in caplog.text
+
+
+def test_callout_fallback_on_empty_body(caplog):
+    """callout with empty body is reclassified to key_insight."""
+    import logging
+
+    from tutor.generation.segment_parser import _validate_segment
+    from tutor.models import SlideSegment
+
+    seg = SlideSegment(
+        unit_index=1,
+        segment_index=0,
+        lines_start=0,
+        lines_end=1,
+        visual_type="callout",
+        title="WARNING",
+        body=None,
+        code=None,
+        language=None,
+        mermaid=None,
+        left=None,
+        right=None,
+        rows=None,
+    )
+    with caplog.at_level(logging.WARNING):
+        result = _validate_segment(seg)
+    assert result.visual_type == "key_insight"
+    assert "callout" in caplog.text
+
+
+def test_valid_step_sequence_passes_validation():
+    """step_sequence with body is accepted without reclassification."""
+    from tutor.generation.segment_parser import _validate_segment
+    from tutor.models import SlideSegment
+
+    seg = SlideSegment(
+        unit_index=1,
+        segment_index=0,
+        lines_start=0,
+        lines_end=2,
+        visual_type="step_sequence",
+        title="How to deploy",
+        body="Open the terminal\nRun the build script\nPush to staging",
+        code=None,
+        language=None,
+        mermaid=None,
+        left=None,
+        right=None,
+        rows=None,
+    )
+    result = _validate_segment(seg)
+    assert result.visual_type == "step_sequence"
+
+
+def test_valid_callout_passes_validation():
+    """callout with title and body is accepted without reclassification."""
+    from tutor.generation.segment_parser import _validate_segment
+    from tutor.models import SlideSegment
+
+    seg = SlideSegment(
+        unit_index=1,
+        segment_index=0,
+        lines_start=4,
+        lines_end=5,
+        visual_type="callout",
+        title="TIP",
+        body="Always run the linter before committing — it catches 80% of review feedback.",
+        code=None,
+        language=None,
+        mermaid=None,
+        left=None,
+        right=None,
+        rows=None,
+    )
+    result = _validate_segment(seg)
+    assert result.visual_type == "callout"
+
+
+def test_visual_planner_plan_visuals_still_callable(tmp_path):
+    from dataclasses import asdict as _asdict
+
+    from tutor.generation.visual_planner import plan_visuals
+    from tutor.models import TeachingUnit
+
+    unit = TeachingUnit(
+        unit=1,
+        concept="Test Concept",
+        source_sections=["s01"],
+        complexity=1,
+        word_budget=200,
+        key_facts=["fact1"],
+        common_misconception="none",
+        good_analogy="like a box",
+        question_style="recall",
+        memory_hook="remember the box",
+    )
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([_asdict(unit)]), encoding="utf-8")
+
+    def stub_llm(messages, call_type="visual"):
+        return json.dumps(
+            {
+                "hook_question": "What is it?",
+                "key_points": ["Point one"],
+                "code_snippet": None,
+                "diagram_type": "none",
+                "diagram_spec": None,
+                "memory_hook": "remember",
+                "analogy": "",
+            }
+        )
+
+    video_dir = tmp_path / "video"
+    specs = plan_visuals(units_json, "Test", "test_session", stub_llm, "beginner", video_dir)
+    assert len(specs) >= 1

tutor/tests/generation/test_visual_planner.py

@@ -0,0 +1,319 @@
+import json
+from dataclasses import asdict
+
+from tutor.generation.visual_planner import (
+    _build_outro,
+    _build_title_card,
+    _cache_path,
+    _fallback_spec,
+    _parse_visual_response,
+    _plan_unit,
+    plan_visuals,
+)
+from tutor.models import TeachingUnit, VisualSpec
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def _make_unit(idx: int = 1, concept: str = "Pass-by-Value") -> TeachingUnit:
+    return TeachingUnit(
+        unit=idx,
+        concept=concept,
+        source_sections=["s01"],
+        complexity=2,
+        word_budget=400,
+        key_facts=["Java passes copies", "Primitives copy values", "References copy the pointer"],
+        common_misconception="Java passes objects by reference",
+        good_analogy="Copying an address, not a house",
+        question_style="recall",
+        memory_hook="Copy the address, not the house",
+    )
+
+
+def _make_units(n: int = 2) -> list[TeachingUnit]:
+    concepts = ["Pass-by-Value", "String Equality", "Interfaces", "Abstract Classes"]
+    return [_make_unit(i + 1, concepts[i % len(concepts)]) for i in range(n)]
+
+
+GOOD_LLM_RESPONSE = json.dumps(
+    {
+        "hook_question": "What really happens when Java passes an object?",
+        "key_points": [
+            "Java always passes copies",
+            "Primitive copies hold the value directly",
+            "Reference copies hold the memory address",
+        ],
+        "code_snippet": "void mutate(int x) { x = 99; }",
+        "diagram_type": "flowchart",
+        "diagram_spec": "digraph G { rankdir=TB\n A -> B }",
+        "memory_hook": "Copy the address, not the house",
+    }
+)
+
+CODE_COMPARISON_RESPONSE = json.dumps(
+    {
+        "hook_question": "Which equality check should you use?",
+        "key_points": ["Use .equals() for content", "== checks identity"],
+        "code_snippet": None,
+        "diagram_type": "code_comparison",
+        "diagram_spec": {
+            "wrong": "if (a == b) {}",
+            "right": "if (a.equals(b)) {}",
+            "label_wrong": "compares references",
+            "label_right": "compares content",
+        },
+        "memory_hook": "equals for content, == for identity",
+    }
+)
+
+
+def fake_llm(messages, call_type="dialogue"):
+    return GOOD_LLM_RESPONSE
+
+
+# ---------------------------------------------------------------------------
+# _parse_visual_response
+# ---------------------------------------------------------------------------
+
+
+def test_parse_good_response_returns_visual_spec():
+    unit = _make_unit()
+    spec = _parse_visual_response(GOOD_LLM_RESPONSE, unit)
+    assert isinstance(spec, VisualSpec)
+    assert spec.slide_type == "unit"
+    assert spec.concept == unit.concept
+    assert spec.diagram_type == "flowchart"
+    assert spec.hook_question != ""
+
+
+def test_parse_code_comparison_response():
+    unit = _make_unit()
+    spec = _parse_visual_response(CODE_COMPARISON_RESPONSE, unit)
+    assert spec.diagram_type == "code_comparison"
+    assert isinstance(spec.diagram_spec, dict)
+    assert "wrong" in spec.diagram_spec
+    assert "right" in spec.diagram_spec
+
+
+def test_invalid_json_returns_fallback():
+    unit = _make_unit()
+    spec = _parse_visual_response("not json at all %%%", unit)
+    assert spec.diagram_type == "none"
+    assert spec.diagram_spec is None
+    assert spec.concept == unit.concept
+
+
+def test_invalid_diagram_type_becomes_none():
+    unit = _make_unit()
+    bad = json.dumps(
+        {
+            "hook_question": "Q?",
+            "key_points": ["fact"],
+            "code_snippet": None,
+            "diagram_type": "pie_chart",
+            "diagram_spec": None,
+            "memory_hook": "remember this",
+        }
+    )
+    spec = _parse_visual_response(bad, unit)
+    assert spec.diagram_type == "none"
+
+
+def test_dot_diagram_without_valid_dot_string_becomes_none():
+    unit = _make_unit()
+    bad = json.dumps(
+        {
+            "hook_question": "Q?",
+            "key_points": ["fact"],
+            "code_snippet": None,
+            "diagram_type": "class_diagram",
+            "diagram_spec": "this is not dot syntax",
+            "memory_hook": "remember",
+        }
+    )
+    spec = _parse_visual_response(bad, unit)
+    assert spec.diagram_type == "none"
+    assert spec.diagram_spec is None
+
+
+def test_code_comparison_missing_keys_becomes_none():
+    unit = _make_unit()
+    bad = json.dumps(
+        {
+            "hook_question": "Q?",
+            "key_points": ["fact"],
+            "code_snippet": None,
+            "diagram_type": "code_comparison",
+            "diagram_spec": {"only_wrong": "x = 1"},
+            "memory_hook": "remember",
+        }
+    )
+    spec = _parse_visual_response(bad, unit)
+    assert spec.diagram_type == "none"
+
+
+# ---------------------------------------------------------------------------
+# _fallback_spec
+# ---------------------------------------------------------------------------
+
+
+def test_fallback_spec_fields():
+    unit = _make_unit()
+    spec = _fallback_spec(unit)
+    assert spec.slide_type == "unit"
+    assert spec.diagram_type == "none"
+    assert spec.diagram_spec is None
+    assert spec.unit_index == unit.unit
+    assert len(spec.key_points) <= 5
+
+
+# ---------------------------------------------------------------------------
+# _build_title_card / _build_outro
+# ---------------------------------------------------------------------------
+
+
+def test_title_card_slide_type():
+    units = _make_units(3)
+    card = _build_title_card("Java Basics", units, "week1_1")
+    assert card.slide_type == "title_card"
+    assert card.unit_index == 0
+    assert "3 units" in card.subtitle
+    assert card.title == "Java Basics"
+
+
+def test_outro_collects_memory_hooks():
+    units = _make_units(2)
+    outro = _build_outro(units)
+    assert outro.slide_type == "outro"
+    assert outro.unit_index == len(units) + 1
+    assert len(outro.memory_hooks) == len(units)
+    assert units[0].memory_hook in outro.memory_hooks
+
+
+# ---------------------------------------------------------------------------
+# _plan_unit — caching
+# ---------------------------------------------------------------------------
+
+
+def test_cache_hit_skips_llm(tmp_path):
+    unit = _make_unit()
+    cache_file = tmp_path / "test.visual.json"
+    spec = _fallback_spec(unit)
+    cache_file.write_text(json.dumps(asdict(spec)), encoding="utf-8")
+
+    call_count = {"n": 0}
+
+    def counting_llm(messages, call_type="dialogue"):
+        call_count["n"] += 1
+        return GOOD_LLM_RESPONSE
+
+    result = _plan_unit(unit, counting_llm, "beginner", cache_file)
+    assert call_count["n"] == 0
+    assert result.concept == unit.concept
+
+
+def test_cache_miss_calls_llm(tmp_path):
+    unit = _make_unit()
+    cache_file = tmp_path / "missing.visual.json"
+
+    call_count = {"n": 0}
+
+    def counting_llm(messages, call_type="dialogue"):
+        call_count["n"] += 1
+        return GOOD_LLM_RESPONSE
+
+    _plan_unit(unit, counting_llm, "beginner", cache_file)
+    assert call_count["n"] == 1
+    assert cache_file.exists()
+
+
+def test_llm_failure_produces_fallback_not_crash(tmp_path):
+    unit = _make_unit()
+    cache_file = tmp_path / "x.visual.json"
+
+    def bad_llm(messages, call_type="dialogue"):
+        raise RuntimeError("API exploded")
+
+    spec = _plan_unit(unit, bad_llm, "beginner", cache_file)
+    assert spec.diagram_type == "none"
+    assert spec.concept == unit.concept
+
+
+# ---------------------------------------------------------------------------
+# plan_visuals — integration
+# ---------------------------------------------------------------------------
+
+
+def test_plan_visuals_returns_title_and_outro(tmp_path):
+    units = _make_units(2)
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(
+        json.dumps([asdict(u) for u in units], ensure_ascii=False),
+        encoding="utf-8",
+    )
+    video_dir = tmp_path / "video"
+
+    specs = plan_visuals(units_json, "Java Basics", "week1_1", fake_llm, "beginner", video_dir)
+
+    assert specs[0].slide_type == "title_card"
+    assert specs[-1].slide_type == "outro"
+    assert len(specs) == len(units) + 2
+
+
+def test_plan_visuals_writes_json_to_video_dir(tmp_path):
+    units = _make_units(1)
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([asdict(u) for u in units]), encoding="utf-8")
+    video_dir = tmp_path / "video"
+
+    plan_visuals(units_json, "Java Basics", "week1_1", fake_llm, "beginner", video_dir)
+
+    out = video_dir / "tutorial.visuals.json"
+    assert out.exists()
+    data = json.loads(out.read_text(encoding="utf-8"))
+    assert isinstance(data, list)
+    assert data[0]["slide_type"] == "title_card"
+
+
+def test_plan_visuals_no_cache_clears_cache(tmp_path):
+    unit = _make_unit()
+    cache_file = _cache_path(unit, "beginner")
+    cache_file.parent.mkdir(parents=True, exist_ok=True)
+    cache_file.write_text(json.dumps(asdict(_fallback_spec(unit))), encoding="utf-8")
+
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([asdict(unit)]), encoding="utf-8")
+    video_dir = tmp_path / "video"
+
+    call_count = {"n": 0}
+
+    def counting_llm(messages, call_type="dialogue"):
+        call_count["n"] += 1
+        return GOOD_LLM_RESPONSE
+
+    plan_visuals(units_json, "T", "s", counting_llm, "beginner", video_dir, no_cache=True)
+    assert call_count["n"] == 1
+
+
+def test_unit_specs_have_required_fields(tmp_path):
+    units = _make_units(2)
+    units_json = tmp_path / "tutorial.units.json"
+    units_json.write_text(json.dumps([asdict(u) for u in units]), encoding="utf-8")
+    video_dir = tmp_path / "video"
+
+    specs = plan_visuals(units_json, "T", "s", fake_llm, "beginner", video_dir)
+    unit_specs = [s for s in specs if s.slide_type == "unit"]
+
+    for spec in unit_specs:
+        assert spec.concept
+        assert isinstance(spec.key_points, list)
+        assert spec.diagram_type in {
+            "class_diagram",
+            "flowchart",
+            "code_comparison",
+            "concept_map",
+            "none",
+        }
+        assert spec.memory_hook is not None