manga-recap-pipeline/caveats/speaker-attribution.md

speaker-attribution

Limits found by cross-checking the 2026-08-11 chapter run against the panel images.

speaker_method="tail" never reads a tail

worker_vision.py:376 (_annotate_speaker_methods) stamps tail on any line whose speaker matches a local_id present in the panel. No balloon geometry is consulted. The caller keeps gemma's confidence, usually 1.0. An unverified model guess thus carries the highest-trust provenance in the pipeline. The review UI and the flag rules both believe it.

Measured on job 778297bc, chapter 7c944dd4: 31 of 81 speech lines are tail with two or more characters present. Three two-character panels were checked against the art, and all three are wrong, each with the two speakers swapped:

panel key	line	truth	pipeline
p010.png	"…definitely an Egen guy, Seonho!"	the woman	Seonho, the person addressed
p010.png	"Y-you think so?"	Seonho	Choi Haeseon
p012.png	"Want me to send you the link?"	the woman	the man
p059.png	"If team leader Choi says it, it must be true."	the man	Choi Haeseon

The last row needs no image: the line refers to Choi in the third person and is attributed to Choi.

The grounded path exists and almost never fires. Only 2 of 81 speech lines got som_face, because attribution marks need face_detect boxes that survive _pair_faces_to_present, and these webtoon close-ups rarely produce them. Inference, not measured: the face detector was not instrumented.

worker_vision.py:356 already carries the ponytail: note that multi-character attribution needs per-balloon geometry. bubble_detect.py:9 records that the det/seg heads carry balloon fill and tail tips and are unused.

Revisit trigger: the share of narrated lines with a named speaker is the Phase 1 headline metric (ROADMAP.md). It reads 30% on this run, and the sample says that 30% is itself unreliable. The metric cannot be trusted until this is fixed. Fix order: stop stamping a guess as tail at confidence 1.0. Prefer unknown when two or more characters are present. Then bind by tail geometry.

One character id covers two different women

character_afa7623b is stored as "black bob, white sweater" and is assigned both to that person (p059.png) and to the brown-bob green-top coworker (p010.png, p012.png). It took 25 of the 26 identity assignments in the chapter, against 113 detected people. Coverage is 23%.

Revisit trigger: any work on the identity Tier-2 decider. A single id absorbing a whole chapter is the signature to watch for.

The character registry carries five weeks of wrong names

The registry holds 53 characters for manga ef105a86, 41 of them unnamed, with "Kei" three times and "Kanade" twice. Kei, Kanade, Zen, Rico, K3, and Watanabe occur zero times in this chapter's text. Only Haeseon and Seonho do. /stage/clear leaves the per-manga registry intact by design, so every rerun inherits the whole pile.

Revisit trigger: before any run that is meant to produce a clean baseline. Either scope the registry to a chapter or add a reviewed reset.

A multi-word character name always fails the script verifier

correctness.py:174 builds allowed from cast_names verbatim, so a two-word name enters the set as one string, "choi haeseon". _capitalized_tokens then yields the tokens Choi and Haeseon separately, neither of which is in allowed. Every beat whose narration uses a two-word name fails with unsupported-proper-noun. A one-word name such as Seonho passes, which is why this went unseen.

Measured on job 778297bc: the script stage failed at 87/116. 28 of the 29 lost beats cite ['Choi', 'Haeseon'], one cites ['Blur'], an onomatopoeia the model invented.

Fix: tokenize each cast name when building allowed, in verify_script (/mnt/server/home/kami/docker-apps/manga-infra/orchestrator/correctness.py:174). One line. Existing test_script_verify.py covers the function, so add the two-word case there.

Revisit trigger: immediately. It costs a quarter of the chapter's narration on any title whose cast has a surname.