File size: 24,679 Bytes
7e20c47
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4b46ff9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7e20c47
 
4b46ff9
 
 
 
 
 
7e20c47
4b46ff9
7e20c47
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5c072a9
 
 
 
 
 
 
 
7e20c47
 
 
 
 
 
5c072a9
7e20c47
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5d9159c
7e20c47
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5d9159c
7e20c47
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5d9159c
7e20c47
 
 
 
 
 
 
 
 
 
 
 
 
 
5c072a9
 
 
 
 
 
 
 
 
 
 
 
 
5d9159c
5c072a9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5d9159c
5c072a9
 
 
 
 
5d9159c
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5d54c1c
 
 
5d9159c
 
 
 
 
 
 
5d54c1c
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7e20c47
 
5d9159c
7e20c47
5d9159c
7e20c47
 
 
9a92330
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6dd9ac4
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
e8ba7af
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1361034
 
 
 
 
 
 
 
 
 
 
 
 
6dd9ac4
 
 
 
 
 
 
 
 
 
 
5d1a426
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9a92330
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
"""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()