"""Tests for the topic-segmentation pipeline branch. Covers the two deterministic pieces — schedule validation and the re-bucketing of scene frames into topic-segments. The LLM call itself is network-bound and excluded from unit tests. """ from pathlib import Path import pytest from app.pipeline.llm_extract import ( LLMTopicError, Topic, _ExtractedTopic, _validate_topics, ) from app.pipeline.orchestrator import _apply_topic_segmentation from app.pipeline.types import SceneFrame # --------------------------------------------------------------------------- # _validate_topics # --------------------------------------------------------------------------- def _et(start: float, end: float, title: str = "T", summary: str = "") -> _ExtractedTopic: return _ExtractedTopic(start_seconds=start, end_seconds=end, title=title, summary=summary) def test_validate_topics_rejects_empty_list(): with pytest.raises(LLMTopicError, match="no topics"): _validate_topics([], total_duration=60.0, transcript_start=0.0) def test_validate_topics_drops_missing_title_keeps_valid_neighbours(): """A single missing-title topic from the LLM shouldn't tank the whole job — drop it and keep the rest. """ out = _validate_topics( [_et(0.0, 30.0, title=""), _et(30.0, 60.0, title="ok")], total_duration=60.0, transcript_start=0.0, ) assert len(out) == 1 assert out[0].title == "ok" def test_validate_topics_repairs_reversed_start_end_by_swapping(): """Real failure mode from a deployed job: the LLM returned a topic with end (31) before start (35). Previously we raised and failed the whole job. Now we swap and keep going. """ out = _validate_topics( [ _et(0.0, 30.0, "Intro"), _et(35.0, 31.0, "Why climate education matters"), # reversed _et(40.0, 60.0, "Outro"), ], total_duration=60.0, transcript_start=0.0, ) titles = [t.title for t in out] assert "Why climate education matters" in titles repaired = next(t for t in out if t.title == "Why climate education matters") assert repaired.start_seconds <= repaired.end_seconds def test_validate_topics_drops_zero_length_topic_keeps_neighbours(): """A topic with start == end (still degenerate after repair) is dropped; the rest survive. """ out = _validate_topics( [ _et(0.0, 30.0, "Intro"), _et(30.0, 30.0, "Zero length"), _et(30.0, 60.0, "Outro"), ], total_duration=60.0, transcript_start=0.0, ) titles = [t.title for t in out] assert "Zero length" not in titles assert "Intro" in titles and "Outro" in titles def test_validate_topics_raises_when_every_topic_is_malformed(): """If literally every topic is unsalvageable, the LLM call is a bust — raise so the job surfaces a real error rather than silently producing an empty guide. """ with pytest.raises(LLMTopicError, match="malformed"): _validate_topics( [_et(10.0, 10.0, title=""), _et(20.0, 20.0, title="")], total_duration=60.0, transcript_start=0.0, ) def test_validate_topics_snaps_small_overlap_to_previous_end(): """LLM sometimes returns end-times that slightly overlap the next topic's start (rounding). We snap to enforce monotonic non-overlap rather than reject — the boundary is approximate anyway. """ out = _validate_topics( [_et(0.0, 30.5, "Intro"), _et(30.0, 60.0, "Body")], total_duration=60.0, transcript_start=0.0, ) assert len(out) == 2 assert out[0].end_seconds == 30.5 assert out[1].start_seconds == 30.5 # snapped forward assert out[1].end_seconds == 60.0 def test_validate_topics_drops_topic_swallowed_by_snap(): """If snapping makes a topic's start >= its own end, the previous topic effectively swallowed it; drop the collapsed one rather than emit a zero-length segment. """ out = _validate_topics( [_et(0.0, 40.0, "Intro"), _et(10.0, 35.0, "Inside intro")], total_duration=60.0, transcript_start=0.0, ) assert len(out) == 1 assert out[0].title == "Intro" def test_validate_topics_pins_head_and_tail_to_full_timeline(): """The orchestrator passes the actual video duration; the LLM's last topic should extend to cover any narration after the last cue boundary it picked, and its first should reach back to the start. """ out = _validate_topics( [_et(5.0, 40.0, "Intro"), _et(40.0, 55.0, "Outro")], total_duration=70.0, transcript_start=0.0, ) assert out[0].start_seconds == 0.0 assert out[-1].end_seconds == 70.0 def test_validate_topics_sorts_out_of_order_input(): out = _validate_topics( [_et(40.0, 60.0, "Late"), _et(0.0, 40.0, "Early")], total_duration=60.0, transcript_start=0.0, ) assert [t.title for t in out] == ["Early", "Late"] # --------------------------------------------------------------------------- # _apply_topic_segmentation # --------------------------------------------------------------------------- def _sf( idx: int, start: float, end: float, *, alts: int = 0, face_area_ratio: float = 0.0, ) -> SceneFrame: return SceneFrame( index=idx, start_seconds=start, end_seconds=end, image_path=Path(f"scene_{idx:04d}.jpg"), alt_image_paths=[Path(f"scene_{idx:04d}_alt{j}.jpg") for j in range(1, alts + 1)], face_area_ratio=face_area_ratio, ) def test_apply_topic_segmentation_collapses_scenes_under_one_topic(): """The canonical case: 4 scenes, 2 topics. Each topic-segment carries the longest-on-screen scene as primary and the others as additional alternates the reviewer can switch to in the editor. """ scenes = [ _sf(0, 0.0, 5.0), _sf(1, 5.0, 25.0, alts=2), # longest in topic 0 — should be primary _sf(2, 25.0, 35.0), _sf(3, 35.0, 55.0, alts=2), # longest in topic 1 — should be primary ] topics = [ Topic(start_seconds=0.0, end_seconds=30.0, title="Setup"), Topic(start_seconds=30.0, end_seconds=60.0, title="Heat pumps"), ] new_kept, titles, summaries, _ = _apply_topic_segmentation(scenes, topics) assert len(new_kept) == 2 assert titles == ["Setup", "Heat pumps"] # Topic 0: scene 1 wins (20s vs 5s + 10s); scenes 0 and 2 attached as alts. assert new_kept[0].image_path.name == "scene_0001.jpg" assert new_kept[0].start_seconds == 0.0 assert new_kept[0].end_seconds == 30.0 alt_names_0 = [p.name for p in new_kept[0].alt_image_paths] # Scene 1's within-scene candidate alts come first… assert "scene_0001_alt1.jpg" in alt_names_0 assert "scene_0001_alt2.jpg" in alt_names_0 # …then the other scenes' primary frames. assert "scene_0000.jpg" in alt_names_0 assert "scene_0002.jpg" in alt_names_0 # Topic 1: scene 3 wins; scene 2 (assigned to topic 1 if its start fell # inside) — actually scene 2 starts at 25.0 which is in topic 0, so # topic 1 only has scene 3. assert new_kept[1].image_path.name == "scene_0003.jpg" assert new_kept[1].start_seconds == 30.0 assert new_kept[1].end_seconds == 60.0 def test_apply_topic_segmentation_drops_empty_topics(): """A topic with no scenes (e.g. LLM imagined a section in a visually static stretch) is dropped — a segment with no image has no place in the editor. """ scenes = [_sf(0, 0.0, 5.0), _sf(1, 5.0, 25.0)] topics = [ Topic(start_seconds=0.0, end_seconds=30.0, title="Real"), Topic(start_seconds=30.0, end_seconds=60.0, title="Empty"), ] new_kept, titles, summaries, _ = _apply_topic_segmentation(scenes, topics) assert len(new_kept) == 1 assert titles == ["Real"] def test_apply_topic_segmentation_buckets_outlier_scenes_into_nearest_topic(): """If the LLM trims the time range tight, a scene whose start lies just outside any topic range falls back to the closest topic by edge distance — better than dropping it. """ scenes = [ _sf(0, 0.0, 5.0), # before any topic _sf(1, 10.0, 25.0), _sf(2, 80.0, 95.0), # after the last topic ] topics = [ Topic(start_seconds=8.0, end_seconds=30.0, title="Mid"), Topic(start_seconds=30.0, end_seconds=70.0, title="End"), ] new_kept, titles, _, _ = _apply_topic_segmentation(scenes, topics) assert len(new_kept) == 2 # Scene 0 (start=0) is closer to topic[0].start=8 than to either # edge of topic[1]; ends up in topic 0's alts. topic0_alts = [p.name for p in new_kept[0].alt_image_paths] assert "scene_0000.jpg" in topic0_alts # Scene 2 (start=80) is closer to topic[1].end=70 than any topic 0 # edge; ends up in topic 1. topic1_paths = ( new_kept[1].image_path.name, *[p.name for p in new_kept[1].alt_image_paths], ) assert "scene_0002.jpg" in topic1_paths def test_apply_topic_segmentation_prefers_slide_content_over_borderline_face(): """A topic that contains both a long borderline-face scene and a shorter clean-slide scene should anchor on the slide, not the face. Without the face_area_ratio tiebreak, the longer talking-head shot would win on duration alone. """ scenes = [ # Long but borderline talking-head (face >3% of frame) _sf(0, 0.0, 40.0, face_area_ratio=0.08), # Shorter but clean slide content (no face) _sf(1, 40.0, 55.0, face_area_ratio=0.0), ] topics = [Topic(start_seconds=0.0, end_seconds=60.0, title="Heat pumps")] new_kept, _, _, _ = _apply_topic_segmentation(scenes, topics) assert len(new_kept) == 1 # Scene 1 (clean) wins despite being shorter. assert new_kept[0].image_path.name == "scene_0001.jpg" # Scene 0 (the borderline) is still available as an alternate so # the reviewer can pick it if they want. alt_names = [p.name for p in new_kept[0].alt_image_paths] assert "scene_0000.jpg" in alt_names def test_apply_topic_segmentation_falls_back_when_all_scenes_are_borderline(): """If every scene in a topic has a borderline face, we still need to pick one — fall back to the longest among them rather than dropping the topic. """ scenes = [ _sf(0, 0.0, 10.0, face_area_ratio=0.08), _sf(1, 10.0, 30.0, face_area_ratio=0.10), # longest borderline _sf(2, 30.0, 40.0, face_area_ratio=0.06), ] topics = [Topic(start_seconds=0.0, end_seconds=40.0, title="All borderline")] new_kept, _, _, _ = _apply_topic_segmentation(scenes, topics) assert len(new_kept) == 1 # Scene 1 wins on duration in the borderline pool. assert new_kept[0].image_path.name == "scene_0001.jpg" def test_apply_topic_segmentation_prefers_scene_with_slide_text_over_talking_head(): """The hard case from real lectures: a topic contains a long talking-head scene (no OCR text, face below the filter's drop threshold so it survived) and a shorter scene with real slide content. The OCR-text signal must dominate face-area and duration so the slide wins as primary. """ scenes = [ # Long talking-head shot, no OCR text but a small visible face. _sf(0, 0.0, 40.0, face_area_ratio=0.06), # Shorter clean slide with substantial OCR'd text. _sf(1, 40.0, 50.0, face_area_ratio=0.0), ] topics = [Topic(start_seconds=0.0, end_seconds=60.0, title="Heat pumps")] new_kept, _, _, primary_ocr = _apply_topic_segmentation( scenes, topics, scene_ocr_texts=[ "", # talking head: no on-screen text "Learning outcomes: identify climate education definitions and goals", ], ) assert len(new_kept) == 1 assert new_kept[0].image_path.name == "scene_0001.jpg" assert "Learning outcomes" in primary_ocr[0] # The talking head is still available as an alternate. alt_names = [p.name for p in new_kept[0].alt_image_paths] assert "scene_0000.jpg" in alt_names def test_apply_topic_segmentation_falls_back_to_face_area_when_no_scene_has_slide_text(): """If no scene in a topic has substantial OCR text (intro stretch, pure Q&A), the picker falls back to face-area: prefer the cleanest face frame even though none of them are slides. """ scenes = [ # Long but borderline face area. _sf(0, 0.0, 30.0, face_area_ratio=0.08), # Shorter and cleaner. _sf(1, 30.0, 45.0, face_area_ratio=0.0), ] topics = [Topic(start_seconds=0.0, end_seconds=50.0, title="Intro")] new_kept, _, _, _ = _apply_topic_segmentation( scenes, topics, scene_ocr_texts=["", ""] ) assert len(new_kept) == 1 # Scene 1 (no face) wins over the longer scene 0 (borderline face). assert new_kept[0].image_path.name == "scene_0001.jpg" def test_apply_topic_segmentation_returns_ocr_aligned_to_new_primaries(): """The fourth return value carries the OCR text of whichever scene became each topic's primary. The orchestrator threads this back into its ocr_texts list so downstream rendering doesn't re-OCR. """ scenes = [ _sf(0, 0.0, 10.0), _sf(1, 10.0, 25.0), # primary by duration _sf(2, 30.0, 50.0), # primary by duration ] topics = [ Topic(start_seconds=0.0, end_seconds=30.0, title="A"), Topic(start_seconds=30.0, end_seconds=60.0, title="B"), ] new_kept, _, _, primary_ocr = _apply_topic_segmentation( scenes, topics, scene_ocr_texts=[ "Slide zero text", # any non-empty OCR output = real slide content "Slide one text", "Slide two content", ], ) assert len(new_kept) == 2 assert "Slide one" in primary_ocr[0] assert "Slide two" in primary_ocr[1] def test_apply_topic_segmentation_short_title_card_beats_longer_talking_head(): """User-reported regression from the heat-pump lecture: a short "HEAT PUMPS" title card OCRs to roughly 10 characters and the old 30-char floor dropped it out of the slide_text pool, so a longer talking-head shot won by duration. With the relaxed "any non-empty OCR" check, the title card wins as it should. """ scenes = [ # Long borderline talking-head, no OCR text. _sf(0, 0.0, 40.0, face_area_ratio=0.08), # Short title-card slide with just "HEAT PUMPS". _sf(1, 40.0, 50.0, face_area_ratio=0.0), ] topics = [Topic(start_seconds=0.0, end_seconds=60.0, title="Heat pumps")] new_kept, _, _, primary_ocr = _apply_topic_segmentation( scenes, topics, scene_ocr_texts=["", "HEAT PUMPS"], ) assert len(new_kept) == 1 assert new_kept[0].image_path.name == "scene_0001.jpg" assert primary_ocr[0] == "HEAT PUMPS" def test_apply_topic_segmentation_handles_empty_input(): """Defensive: no scenes or no topics → return inputs unchanged.""" assert _apply_topic_segmentation([], []) == ([], [], [], []) scenes = [_sf(0, 0.0, 5.0)] out_kept, titles, summaries, _ = _apply_topic_segmentation(scenes, []) assert out_kept == scenes assert titles == [""] assert summaries == [""] # --------------------------------------------------------------------------- # Image-augmented topic segmentation: verify the request shape, since the # network call itself is out of scope for unit tests. # --------------------------------------------------------------------------- def test_extract_topics_with_images_attaches_thumbnails(monkeypatch, tmp_path): """When the with-images sub-toggle is on, the user content posted to Claude must include both the transcript text and one image block per kept scene. Verifies we don't accidentally send a text-only call when the caller asked for visual context. """ from PIL import Image as _Image from app.pipeline import llm_extract from app.pipeline.transcript import Cue # Create three tiny on-disk frames so _thumbnail_b64 has something # to read. frames: list[tuple[float, _Image.Image]] = [] paths: list = [] for i in range(3): p = tmp_path / f"scene_{i:04d}.jpg" _Image.new("RGB", (200, 120), color=(i * 60, 80, 200)).save(p, "JPEG") paths.append(p) frame_inputs = [(float(i) * 10.0, p) for i, p in enumerate(paths)] cues = [Cue(start=0.0, end=4.0, text="Intro.")] # Stub the API: capture the user content and return a valid topic. captured: dict = {} class _StubMessages: def parse(self, **kwargs): captured["messages"] = kwargs["messages"] captured["system"] = kwargs["system"] class _Resp: parsed_output = llm_extract._ExtractedTopicList( topics=[ llm_extract._ExtractedTopic( start_seconds=0.0, end_seconds=30.0, title="Whole video", summary="", ) ] ) return _Resp() class _StubClient: def __init__(self, *_a, **_kw): self.messages = _StubMessages() monkeypatch.setattr(llm_extract, "_build_client", lambda key: _StubClient()) monkeypatch.setattr(llm_extract, "_resolve_api_key", lambda key: "stub-key") topics = llm_extract.extract_topics( cues, total_duration=30.0, api_key="stub-key", frames=frame_inputs, ) assert len(topics) == 1 content = captured["messages"][0]["content"] assert isinstance(content, list), "image variant must use the content-list form" # First block is the transcript text; subsequent blocks include one # image per attached frame plus a per-frame text label. text_blocks = [b for b in content if b.get("type") == "text"] image_blocks = [b for b in content if b.get("type") == "image"] assert image_blocks, "expected at least one image block in the request" assert len(image_blocks) == 3, image_blocks # The system prompt must be the with-images variant so Claude knows # how to use the thumbnails. assert "thumbnail" in captured["system"][0]["text"].lower() # And the transcript text is still in there. assert any("Intro." in b["text"] for b in text_blocks) def test_topic_system_prompt_prepends_genre_hint_when_known(): """The video_type parameter should bias the prompt toward the conventional structure of that genre. Verify the hint is actually prepended for each known type and the base prompt is preserved intact after the separator. """ from app.pipeline.llm_extract import _topic_system_prompt, _TOPIC_SYSTEM_PROMPT for vt, marker in [ ("lecture", "classroom lecture"), ("lab", "lab walkthrough"), ("tutorial", "how-to tutorial"), ("interview", "interview"), ("talk", "talk or presentation"), ]: out = _topic_system_prompt(vt, with_images=False) assert marker in out.lower(), f"hint missing for {vt}" # The base prompt must still be present after the genre block. assert "3–15 sequential" in out def test_run_pipeline_raises_clear_error_when_transcript_is_empty(tmp_path, monkeypatch): """An empty transcript silently produced an empty-narration guide before. Fail fast with a message naming the fix instead so the user knows to provide cues / enable auto-transcribe rather than discovering empty paragraphs in the editor. """ import pytest from app.pipeline.orchestrator import ( PipelineError, PipelineInputs, run_pipeline, ) from app.pipeline.types import SceneFrame # Stub the cue loader to return zero cues; bypass scene detection # by providing preselected_frames so the test doesn't need a real # video file or detect-and-extract round-trip. from app.pipeline import orchestrator as _orch monkeypatch.setattr(_orch, "_load_cues", lambda _i: ([], False)) monkeypatch.setattr(_orch, "video_duration", lambda _p: 30.0) frame_path = tmp_path / "scene_0000.jpg" frame_path.write_bytes(b"\xff\xd8\xff\xd9") # minimal JPEG header fake_frame = SceneFrame( index=0, start_seconds=0.0, end_seconds=5.0, image_path=frame_path ) inputs = PipelineInputs( video_path=tmp_path / "v.mp4", transcript_path=tmp_path / "t.vtt", frames_dir=tmp_path, title="t", skip_ocr=True, ) with pytest.raises(PipelineError, match="zero cues"): run_pipeline(inputs, preselected_frames=[fake_frame]) def test_is_valid_video_type_accepts_known_genres_only(): """HTTP handlers use is_valid_video_type to reject typos with a 400 instead of letting the prompt-composer silently fall back to the base prompt with no warning to the user. """ from app.pipeline.llm_extract import is_valid_video_type for known in ("general", "lecture", "lab", "tutorial", "interview", "talk"): assert is_valid_video_type(known), f"{known} should be valid" assert is_valid_video_type(known.upper()), f"{known.upper()} (case) should be valid" for bad in ("", None, "lecutre", "labs", "podcast", "random"): assert not is_valid_video_type(bad), f"{bad!r} should be rejected" def test_topic_system_prompt_unchanged_for_general_or_unknown(): """'general' and unknown video types should not modify the base prompt — we don't want to inject confusing genre advice when the user hasn't picked a genre. """ from app.pipeline.llm_extract import _topic_system_prompt, _TOPIC_SYSTEM_PROMPT assert _topic_system_prompt("general", with_images=False) == _TOPIC_SYSTEM_PROMPT assert _topic_system_prompt("", with_images=False) == _TOPIC_SYSTEM_PROMPT assert _topic_system_prompt("nonsense-genre", with_images=False) == _TOPIC_SYSTEM_PROMPT def test_with_images_prompt_warns_off_talking_head_frames(): """The image-augmented prompt must explicitly tell Claude not to anchor topic boundaries on instructor-on-camera frames — those slip past the scene filter occasionally and would otherwise displace real slides as the topic's representative content. """ from app.pipeline.llm_extract import _TOPIC_SYSTEM_PROMPT_WITH_IMAGES prompt = _TOPIC_SYSTEM_PROMPT_WITH_IMAGES.lower() assert "talking-head" in prompt or "talking head" in prompt # The guidance must say what to do, not just name the failure mode. assert "do not" in prompt or "don't" in prompt # And it must distinguish the legitimate edge case (a stretch with # no slides at all) so the model doesn't pathologically ignore all # face frames. assert "q&a" in prompt or "no slide" in prompt or "pure" in prompt def test_extract_topics_without_images_sends_plain_text(monkeypatch): """When frames is None, the call must use the text-only form (cheaper, faster) and the system prompt must not be the image variant — Claude shouldn't be told to look at slides that aren't in the request. """ from app.pipeline import llm_extract from app.pipeline.transcript import Cue captured: dict = {} class _StubMessages: def parse(self, **kwargs): captured["messages"] = kwargs["messages"] captured["system"] = kwargs["system"] class _Resp: parsed_output = llm_extract._ExtractedTopicList( topics=[ llm_extract._ExtractedTopic( start_seconds=0.0, end_seconds=10.0, title="One", summary="", ) ] ) return _Resp() class _StubClient: def __init__(self, *_a, **_kw): self.messages = _StubMessages() monkeypatch.setattr(llm_extract, "_build_client", lambda key: _StubClient()) monkeypatch.setattr(llm_extract, "_resolve_api_key", lambda key: "stub-key") cues = [Cue(start=0.0, end=4.0, text="Intro.")] llm_extract.extract_topics(cues, total_duration=10.0, api_key="stub-key") content = captured["messages"][0]["content"] assert isinstance(content, str), "text-only variant must send a plain string" assert "thumbnail" not in captured["system"][0]["text"].lower()