# Whole gallery vs. limited (cast-restricted) gallery

Two ways to run the matcher: **full** scores every detected face against the
entire library gallery (2418 actors across the 9-film benchmark set); **restricted**
pre-filters each film's gallery down to just its Jellyfin-credited cast (typically
~15 top-billed actors) before the matcher ever runs.

## The result

Averaged across all 4 models and both expansion settings, on the 4 rep4 training
films:

| scope | F1 | P | R | total misID (8 evals) |
|---|---|---|---|---|
| full | 71.2% | 91.1% | 59.0% | 1073 |
| **restricted** | **74.5%** | 92.2% | **62.9%** | **329** |

This is not a precision/recall trade — restriction wins on every axis at once:
**+3.3pp F1, +3.9pp recall, and less than a third the total misIDs.** Fewer
candidates in the matcher's search space means fewer opportunities for a
look-alike false match (an actor who happens to share enough facial structure
with someone in the film, but isn't actually in it), and the recall gain shows
it isn't costing real detections to get there.

Per-model, every single model's best-scoring combo in the full 16-way matrix is
a `restricted` variant — see the full table in `rep4-optimizer-results.md`. Two
combos hit **zero** true out-of-cast misidentifications:
`arcface_w600k_mbf_restricted_exp` (F1 76.5%) and, in full mode,
`LVFace-B_Glint360K_full_noexp` (F1 72.4%) — restriction isn't the only way to
reach misid=0, but it's the more reliable one.

## Why this isn't the shipped default

Cast-restriction is implemented today only as an **offline optimizer technique**
(`scripts/optimizer/cast_restrict.py`): it pre-builds a filtered gallery file
per film, using Jellyfin's own cast list, before the benchmark ever calls the
matcher. There's no runtime "restrict matching to this title's credited cast"
switch in the shipped application — `scene_analyze` always matches against
whatever single gallery file it's given.

Building that as a real feature would need, at minimum:

- A live Jellyfin cast lookup at analysis time (the title is already known —
  `run_from_jellyfin.py` already does this same lookup for its own
  `filter_gallery`-based restriction path, just not wired into `scene_analyze`
  itself as a first-class option).
- A decision on the *fallback*: what happens to a real, uncredited cameo
  (see the Germar Terrell Gardner case in the LVFace deep-dive) if the gallery
  never includes them at all?
- Regenerating the restricted-gallery cache whenever the title's Jellyfin cast
  list changes.

This is why the shipped `src/config.hpp` defaults use the `full`-mode winner
(`LVFace-B_Glint360K_full_exp`, F1 75.3% training / 67.4% held-out macro) rather
than the higher-scoring `restricted_exp` (78.3%) — the 78.3% number describes a
capability the app doesn't have yet, not what actually ships.